diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..abfd63c --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Check out text files with LF on every platform. Prettier checks for LF, and +# a Windows checkout would otherwise convert them to CRLF. +* text=auto eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b3d07da --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,298 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + check: + name: Check (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 45 + strategy: + fail-fast: false + matrix: + os: [windows-latest, windows-11-arm, macos-latest] + + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-node@v7 + with: + node-version: 24 + cache: npm + + - uses: dtolnay/rust-toolchain@stable + with: + components: rustfmt, clippy + + - uses: Swatinem/rust-cache@v2 + with: + workspaces: src-tauri + + # Puts stackql on PATH so the integration tests run instead of being + # skipped. They use metadata statements and the built-in provider only: + # no credentials and no provider downloads. + - uses: stackql/setup-stackql@v2 + if: matrix.os == 'windows-latest' + + # The MSI for Arm ships the engine built for Arm. The tests run against + # that one, from the release archive, and not against the x64 engine + # under emulation. + - name: Install stackql from the release archive (Windows on Arm) + if: matrix.os == 'windows-11-arm' + shell: pwsh + working-directory: ${{ runner.temp }} + run: | + $base = 'https://github.com/stackql/stackql/releases/latest/download' + curl.exe -fsSL -O "$base/stackql_windows_arm64.zip" + curl.exe -fsSL -O "$base/stackql_windows_arm64.zip.sha256" + $want = ((Get-Content stackql_windows_arm64.zip.sha256) -split '\s+')[0].ToLower() + $have = (Get-FileHash stackql_windows_arm64.zip -Algorithm SHA256).Hash.ToLower() + if ($want -ne $have) { throw 'The archive does not match its checksum.' } + Expand-Archive stackql_windows_arm64.zip -DestinationPath stackql-arm64 + $folder = (Resolve-Path stackql-arm64).Path + Get-ChildItem $folder | Format-Table Name, Length + Add-Content -Path $env:GITHUB_PATH -Value $folder + + # On macOS the setup action installs with Homebrew, which has v0.12.824. + # The tests rely on the current release, so the release package is + # installed instead. It puts stackql in /usr/local/bin. + - name: Install stackql from the release package (macOS) + if: runner.os == 'macOS' + working-directory: ${{ runner.temp }} + run: | + base=https://github.com/stackql/stackql/releases/latest/download + curl -fsSL -O "$base/stackql_darwin_multiarch.pkg" + curl -fsSL -O "$base/stackql_darwin_multiarch.pkg.sha256" + shasum -a 256 -c stackql_darwin_multiarch.pkg.sha256 + sudo installer -pkg stackql_darwin_multiarch.pkg -target / + + - name: Tool versions + shell: bash + run: | + node --version + node -p "'node is built for ' + process.arch" + npm --version + rustc -vV + cargo --version + stackql --version + + - name: Install webview dependencies + run: npm ci + + - name: Lint and format check (webview) + run: npm run lint + + - name: Typecheck (webview) + run: npm run typecheck + + - name: Test (webview) + run: npm test + + - name: Format check (host) + working-directory: src-tauri + run: cargo fmt --check + + - name: Lint (host) + working-directory: src-tauri + run: cargo clippy --all-targets -- -D warnings + + - name: Test (host) + working-directory: src-tauri + run: cargo test + + # Builds the webview bundle and the host together, without installers. + - name: Debug build + run: npm run tauri build -- --debug --no-bundle + + # A test build for a Mac, kept as a workflow artifact. It is not a release: + # the signature is ad hoc, with no Developer ID, and nothing is notarised. + # It does not wait for the checks, so a failing test still leaves a build. + bundle-macos: + name: Bundle (macOS, universal) + runs-on: macos-latest + timeout-minutes: 60 + + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-node@v7 + with: + node-version: 24 + cache: npm + + # A universal build needs the standard library for both architectures. + - uses: dtolnay/rust-toolchain@stable + with: + targets: aarch64-apple-darwin,x86_64-apple-darwin + + - uses: Swatinem/rust-cache@v2 + with: + workspaces: src-tauri + + - name: Install webview dependencies + run: npm ci + + # An Apple Silicon Mac runs no code without a signature. "-" asks for an + # ad hoc one, which needs no certificate. + - name: Build the app and the disk image + env: + APPLE_SIGNING_IDENTITY: '-' + run: npm run tauri build -- --target universal-apple-darwin --bundles app,dmg + + - name: Check the bundle + shell: bash + run: | + bundle=src-tauri/target/universal-apple-darwin/release/bundle + app=$(ls -d "$bundle"/macos/*.app) + archs=$(lipo -archs "$app/Contents/MacOS/stackql-workbench") + echo "Architectures: $archs" + [[ "$archs" == *arm64* && "$archs" == *x86_64* ]] + codesign --verify --deep --strict --verbose=2 "$app" + codesign --display --verbose=2 "$app" + ls -l "$bundle"/dmg + + # The app must stand on its own too. Everything it links to has to be + # part of macOS: a system framework, or a library under /usr/lib. The + # page renderer is one of those frameworks, so there is nothing to ship + # with the app as there is on Windows. + - name: Check what the app asks the system for + shell: bash + run: | + bundle=src-tauri/target/universal-apple-darwin/release/bundle + app=$(ls -d "$bundle"/macos/*.app) + needed=$(otool -L "$app/Contents/MacOS/stackql-workbench" \ + | grep -E '^[[:space:]]' | awk '{print $1}' | sort -u) + echo "$needed" + foreign=$(echo "$needed" | grep -v -E '^(/System/Library/|/usr/lib/)' || true) + if [ -n "$foreign" ]; then + echo "Not part of macOS:" + echo "$foreign" + exit 1 + fi + # Nothing else is carried in the bundle that would have to be signed. + find "$app/Contents" -type f \( -name '*.dylib' -o -name '*.so' \) -print + + # The pages need a renderer of a certain age, and on a Mac the renderer + # is the one that macOS has. The bundle names the oldest macOS it runs + # on, so an older one refuses to open it. Both halves of the executable + # must be built for that version as well. + - name: Check the oldest macOS the app runs on + shell: bash + run: | + bundle=src-tauri/target/universal-apple-darwin/release/bundle + app=$(ls -d "$bundle"/macos/*.app) + want=$(node -p "require('./src-tauri/tauri.conf.json').bundle.macOS.minimumSystemVersion") + declared=$(/usr/libexec/PlistBuddy -c 'Print :LSMinimumSystemVersion' "$app/Contents/Info.plist") + echo "Wanted: $want" + echo "Declared in Info.plist: $declared" + [ "$declared" = "$want" ] + built=$(otool -l "$app/Contents/MacOS/stackql-workbench" \ + | awk '$1 == "minos" {print $2}' | sort -u) + echo "Built for: $built" + [ "$built" = "$want" ] + + - uses: actions/upload-artifact@v7 + with: + name: stackql-workbench-macos-universal + path: src-tauri/target/universal-apple-darwin/release/bundle/dmg/*.dmg + if-no-files-found: error + + # The app on its own, for the StackQL PKG, which installs it beside the + # stackql command and signs what it ships. It is packed with tar because + # a bundle holds links and permissions that a zip of loose files loses. + - name: Pack the app for the installer + shell: bash + run: | + bundle=src-tauri/target/universal-apple-darwin/release/bundle + app=$(ls -d "$bundle"/macos/*.app) + mkdir -p installer-input + tar -czf installer-input/stackql-workbench-macos-universal.app.tar.gz \ + -C "$(dirname "$app")" "$(basename "$app")" + cd installer-input + shasum -a 256 stackql-workbench-macos-universal.app.tar.gz \ + > stackql-workbench-macos-universal.app.tar.gz.sha256 + cat stackql-workbench-macos-universal.app.tar.gz.sha256 + tar -tzf stackql-workbench-macos-universal.app.tar.gz | head -n 12 + + - uses: actions/upload-artifact@v7 + with: + name: stackql-workbench-macos-universal-app + path: installer-input/* + if-no-files-found: error + + # The executable the StackQL MSI installs beside stackql.exe. It is the + # optimised build, with no installer of its own, and it is not signed here: + # the StackQL release signs what it ships. Like the Mac build it does not + # wait for the checks. + # + # The MSI comes for x64 and for arm64, so there is one build for each, made + # on a runner of that processor. Nothing is built across. + build-windows: + name: Build (Windows, ${{ matrix.arch }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + include: + - arch: x64 + os: windows-latest + - arch: arm64 + os: windows-11-arm + + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-node@v7 + with: + node-version: 24 + cache: npm + + - uses: dtolnay/rust-toolchain@stable + + # Kept apart from the cache of the checks, which hold a debug build. + - uses: Swatinem/rust-cache@v2 + with: + workspaces: src-tauri + key: release + + - name: Install webview dependencies + run: npm ci + + - name: Build the executable + run: npm run tauri build -- --no-bundle + + # The executable must stand on its own in the installer's folder. It + # carries its C runtime inside it, so what it asks the system for is + # Windows itself. This reads its import tables and fails on a runtime. + # It also fails when the executable is not built for this processor. + - name: Check what the executable asks the system for + run: node scripts/check-exe-imports.js src-tauri/target/release/stackql-workbench.exe ${{ matrix.arch }} + + - name: Pack the executable for the installer + shell: pwsh + run: | + $exe = 'src-tauri/target/release/stackql-workbench.exe' + New-Item -ItemType Directory -Force installer-input | Out-Null + Copy-Item $exe installer-input/ + $hash = (Get-FileHash installer-input/stackql-workbench.exe -Algorithm SHA256).Hash.ToLower() + "$hash stackql-workbench.exe" | Set-Content installer-input/stackql-workbench.exe.sha256 + Get-Item installer-input/stackql-workbench.exe | Format-List Name, Length + Get-Content installer-input/stackql-workbench.exe.sha256 + + - uses: actions/upload-artifact@v7 + with: + name: stackql-workbench-windows-${{ matrix.arch }} + path: installer-input/* + if-no-files-found: error diff --git a/.gitignore b/.gitignore index c3ec7d2..de5e9d4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,24 +1,33 @@ -# Generated by Cargo -# will have compiled files and executables -debug -target +# Webview build output and dependencies +node_modules/ +dist/ +*.tsbuildinfo +.vitest/ +coverage/ -# These are backup files generated by rustfmt +# Host build output +target/ **/*.rs.bk - -# MSVC Windows builds of rustc generate these, which store debugging information *.pdb +rustc-ice-*.txt +src-tauri/gen/schemas/ -# Generated by cargo mutants -# Contains mutation testing data -**/mutants.out*/ +# Engine working files. The engine writes its cache under --approot and the +# MCP server writes logs to its working directory unless told otherwise. +.stackql/ +.stackqlrc +stackql_mcp_server_*.log +logs/ +*.log -# rustc will dump stack traces when hitting an internal compiler error to PWD -rustc-ice-*.txt +# Secrets and local environment. Never commit these. +.env +.env.* +!.env.example -# RustRover -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ +# Editors and OS +.idea/ +.vscode/* +!.vscode/extensions.json +.DS_Store +Thumbs.db diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..727099c --- /dev/null +++ b/.prettierignore @@ -0,0 +1,11 @@ +dist/ +coverage/ +node_modules/ +package-lock.json +src-tauri/target/ +src-tauri/gen/ +src-tauri/icons/ +# Authored docs keep their own layout. +*.md +# A verbatim copy of an upstream file. +src-tauri/src/icons/providers.snapshot.json diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..554f2a3 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,4 @@ +{ + "singleQuote": true, + "printWidth": 100 +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..46b9637 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,480 @@ +# StackQL Workbench + +This file is the working agreement for coding agents in this repository. Read it and `README.md` in full before changing anything. + +## What this is + +StackQL Workbench is the desktop UI for [StackQL](https://github.com/stackql/stackql). It combines a query IDE with a chat interface over a local `stackql` engine. It is a native app for Windows and macOS, installed beside the `stackql` binary by the StackQL MSI and PKG installers. Linux is out of scope. + +## Status + +Pre-alpha. This much has landed on Windows. + +- M0, foundations: engine discovery and supervision, the pg wire query service, the explorer, one editor buffer and the results grid. +- The core of M3, chat: the MCP client with approvals, the agent loop, the activity pane, and API key backends for Gemini, Anthropic and OpenAI-compatible servers. Anthropic and OpenAI-compatible were M4 items and came along because the backend interface made them cheap. +- The first delegated agent, an M5 item: the GitHub Copilot CLI, driven over the Agent Client Protocol. It uses the sign-in the CLI already has. +- A chat-first layout: chat is the view the app opens in, with a side menu for the explorer and activity, and File, Edit, View, Query, Providers and Help menus. +- Most of M1, the query IDE: editor tabs, completion from provider metadata, the JSON cell viewer, statement history, export as CSV and JSON, and a `stackql exec` command for a statement. +- A query library view: the entries of the published query library, for the operator, with no chat backend needed. +- A conversation that shows a turn as its answer: the calls the assistant made are a list of steps that folds away, a call that failed is written to the app's log and not listed, the result set is a table that sorts and downloads, and a model can ask for a chart with a chart block. + +Not started: the rest of M1 (saved `.iql` files, cancel, a streaming grid), M2 (packaging), plan sign-in and any delegated agent other than the Copilot CLI. Replies from the API key backends are not streamed yet. Replies from the Copilot CLI are. + +CI has a job that builds a universal macOS disk image and keeps it as a workflow artifact, so the app can be tried on a Mac. The signature is ad hoc and nothing is notarised. It is a test build, not M2. + +CI also keeps what the StackQL MSI and PKG are built from: the optimised Windows executable for each processor the MSI comes for, as `stackql-workbench-windows-x64` and `stackql-workbench-windows-arm64`, and the Mac app bundle, packed with tar, as `stackql-workbench-macos-universal-app`. Each comes with its SHA-256. Neither is signed for release. The maintainer said on 19 November 2026 that the StackQL release signs what it ships, so this repository holds no signing identity and signs nothing but the ad hoc signature a Mac needs to run the app at all. Workflow artifacts last 90 days and are not a release. There is no tagged release yet, which is how a shipped build should be pinned. + +What has and has not been run: + +- Everything has been run on Windows 11 x64 against `stackql` v1.0.888. +- The app has not been opened on a Mac. The macOS-only code has run only in tests, on the macOS runner in CI. +- CI first ran on 19 November 2026 and passes on both runners. On macOS that is lint, the 302 webview tests, clippy and 260 host tests against `stackql` v1.0.888: the supervisor, the watchdog and the integration tests that start a real engine. The keychain test reported ok, but it skips itself without failing when the keychain refuses it, so the macOS keychain store is not confirmed. +- The bundle job builds the universal disk image and its checks pass: both architectures are in the executable and the ad hoc signature verifies. +- No Mac older than macOS 13 was tried, so the refusal to open the app there has not been seen. What CI checks is that the bundle declares the minimum. +- Windows on Arm has run only in CI, on GitHub's `windows-11-arm` runner, with the Rust toolchain and Node both built for Arm and `stackql` v1.0.888 from the release's arm64 archive. Lint, the webview tests, clippy and the host tests pass there: 270 unit tests, and the integration tests that start a real engine. The optimised executable built there names arm64 as its processor and asks for the same 19 libraries as the x64 one. The app has not been opened on an Arm machine, and the x64 executable was not tried under emulation. +- Homebrew installs `stackql` v0.12.824. With it two agent tests failed on the macOS runner: a row value arrived as `{"String":"1","Valid":true}`, and tool calls did not overlap. With v1.0.888 from the release package the same tests pass on the same runner, so CI installs the package on macOS. The app does not check the engine's version, which is one of the open questions. +- No API key backend has been run against a real inference provider. Each is tested against a local stub that checks what goes on the wire, and the loop is tested against a real `stackql mcp` with a scripted model. +- The Copilot backend has been run for real, against GitHub Copilot CLI 1.0.113 with a signed-in account. Its protocol handling is also tested against a scripted agent. +- The explorer, completion, history, export through the save dialog, the activity filters, the theme choice and the query library were each driven in the built app on Windows. The "Copy as CLI" commands were run in Windows PowerShell 5.1 and PowerShell 7 against the real engine. The POSIX form was checked in a shell under WSL with a stand-in program, not on macOS. +- The Help menu's links have not been opened by a test. The address each one opens is tested. Help > Show Log File has not been clicked either, since it opens a window on the desktop. The log file it shows was read after real turns. +- The conversation layout, the charts and the sortable table were driven in the built app on Windows in both themes, with a scripted model against the real engine: a declined approval, a call that failed and was not listed, each chart type, a chart that could not be drawn, sorting, and a CSV saved through the save dialog. Two turns were then run for real through the Copilot CLI 1.0.114 on `claude-haiku-4.5`. In the first the model wrote a chart block from the guidance on its first try. In the second three of its calls failed on the way: none was listed, and all three were in the log with their statement or arguments. No API key backend has drawn a chart from a real model. +- Which engine an installed app starts was checked on Windows with a build of the app and a copy of `stackql.exe` in one folder, the way the MSI lays them out. With nothing set it started the engine beside it. With `STACKQL_BIN` naming another engine, and with it pointing nowhere, it still did, and said the variable was not used. With a path in settings it started that engine, and with a path in settings that pointed nowhere it stopped with the reason. The folder was one an ordinary account can write to, so the fallback of the data folder under `Program Files` was not part of this. The macOS rule has run only as unit tests. +- What the Windows executable asks the system for was read from its import tables before and after the C runtime was linked in. Before, it asked for seven libraries of the Universal C runtime. After, for 19 libraries that are all Windows itself. +- The page renderer was checked on Windows 11 with a build of the app in a folder of its own. With nothing beside it, the renderer process ran from the system's WebView2. With a copy of that runtime in a `WebView2Runtime` folder beside it, the renderer process ran from that folder and the app came up with its engine. With a `WebView2Runtime` folder that held no runtime, the system's was used. The copy was of the runtime Windows had installed, version 157, not of Microsoft's Fixed Version package, which has the same layout and was not downloaded. +- No machine without a WebView2 runtime was tried, and no freshly installed Windows 11. A machine without one was imitated on Windows 11 by pointing the loader's variable at an empty folder. The optimised build showed Tauri's own dialog, "Could not find the WebView2 Runtime", with Microsoft's download address, and exited when the dialog was closed. A debug build shows no dialog and only panics. Neither writes the app's log, which starts after the window is made. +- The token counts were seen in the built app with a scripted model, and for real through the Copilot CLI: one prompt to a probe to see what the CLI sends, and one turn through the app, which showed the count on the steps line and in the log. The counts of Gemini, Anthropic and an OpenAI-compatible server are read as their documentation describes and tested against stubs, not against the real services. +- The supervisor's tests see a child end by waiting on a handle to it on Windows, and with `kill -0` on Unix. They used to ask `tasklist`, which on a busy machine could use up the time a test allowed. They passed 30 runs in a row with every core busy. With twice as many busy loops as cores a different test, `an_unexpected_exit_is_reported_with_its_code`, missed its 10 second limit twice in 30 runs. + +Update this section when a milestone lands. The roadmap is in `README.md`. + +## Architecture rules + +These rules are fixed. If one cannot be met, stop and ask instead of working around it. + +- The webview is not served over HTTP and opens no network listener. It loads from the app bundle and reaches the host only through typed IPC commands and events. + - This holds for built apps. `npm run tauri dev` is the one exception: it loads the webview from the Vite dev server, bound to `127.0.0.1:5173`, for hot reload. Nothing in the app may depend on that server existing. +- The webview holds no secrets and makes no direct calls to the engine, to inference providers or to the filesystem. All of that goes through the host. +- The engine is reached over two channels that are not interchangeable. + - Human channel: `stackql srv` over the Postgres wire protocol. Used by the explorer and the editor. Statements here are written or explicitly run by the operator. + - Agent channel: `stackql mcp` over stdio. Used only by the agent runtime. Statements here originate from a model. +- The engine enforces safety. Do not build a second SQL classifier or approval gate in the host. Pass the workspace safety mode to the MCP server and implement the client side of its approval flow. +- All engine access sits behind a `Connection` interface. Only `LocalConnection` exists for now. Code above that interface must not assume the engine is a child process, because a remote connection comes later. +- Inference sits behind one of two seams. A model API sits behind the `InferenceBackend` interface, and the host runs the loop. An agent the operator installed sits behind the ACP client in `agent/acp.rs`, and the agent runs the loop. The chat UI works unchanged across both. +- Chat is the default view. With no backend configured, sending a message opens the model backend settings and keeps what was typed. The explorer and the editor are fully usable without a backend. +- SQL is the interchange between the agent and the operator. Agent-proposed statements are shown as SQL, can be opened in an editor tab, and every executed statement from either channel is recorded in history. +- No Deno, no HTTP middleware tier, no Next.js. The earlier `stackql-playground` and `stackql-middleware` prototypes are reference material for layout and API shape only. + +## Stack + +These are the chosen defaults. Check the current stable version and API of each dependency in its official documentation before using it. Do not rely on memory for library APIs. + +| Layer | Choice | +|---|---| +| Shell | Tauri 2 | +| Host | Rust (stable) with tokio | +| UI | React, TypeScript (strict), Vite | +| Editor | CodeMirror 6 | +| Results grid | TanStack Table with TanStack Virtual | +| Styling | Tailwind CSS | +| pg wire client | `tokio-postgres` | +| MCP client | `rmcp` (the official Rust MCP SDK), client and async read-write transport only | +| Secrets | OS keychain through `keyring-core` with the Windows and Apple native stores | +| Package manager | npm | +| Webview tests | Vitest with jsdom | +| Lint and format | ESLint with typescript-eslint, Prettier, rustfmt, clippy | +| Process supervision | `windows-sys` job object on Windows, process group plus a pipe watchdog on Unix | +| Clipboard | `arboard`, write only, through a host command | +| Save dialog | `tauri-plugin-dialog`, called from host commands only. The webview has no access to it | +| Links | `tauri-plugin-opener`, called from one host command that holds a fixed list of the app's own links, and from the dialog shown when no WebView2 runtime is found | +| Completion | `@codemirror/autocomplete`, with a source written in this repository | +| HTTPS client | `reqwest` with the OS TLS stack (`native-tls`) | +| ACP client | Written in this repository: JSON-RPC over stdio, protocol version 1, the client side only | +| Markdown in replies | Written in this repository: a small reader that builds a tree, never HTML | +| Charts in replies | Written in this repository: a chart block read as data and drawn as SVG. No charting library, in the webview or the host | +| App log | Written in this repository: one JSON lines file for each run, in the app data directory | + +The MCP client library must support the client side of elicitation and protocol revision negotiation. `rmcp` 3.11 does both. That was confirmed against the real engine and is recorded in `docs/spike-mcp.md`. + +The `keyring` crate is now a thin layer over `keyring-core` plus one store crate per platform. The host depends on those directly and installs the platform store at startup. + +Version constraints found while building M0: + +- Rust 1.90 or later. Current Tauri 2 releases need it. Use rustup's stable toolchain, the same one CI uses. +- TypeScript is pinned to 6.0.x. TypeScript 7 ships no compiler API, and typescript-eslint supports up to 6.0. Move to 7 when typescript-eslint does. +- TanStack Table is v9. Its API differs from v8: `useTable`, and features are registered with `tableFeatures`. +- `rmcp` needs Rust 1.88 or later, which the Tauri requirement already covers. + +## Repository layout + +The layout is below. Keep it current as the code lands. + +``` +stackql-workbench/ + src/ webview (React) + host/ typed wrappers over IPC, the only Tauri imports + lib/ pure logic with tests: results, cells, sorting, export formats, explorer tree, statement templates, completion, tabs, history, the CLI command, chat, the conversation layout, the chart block and its layout, activity, the query library, menu, theme, markdown + state/ hooks that connect the host to the panes + panes/ shell (menu bar, side menu), chat, explorer, editor, results, library, activity, settings, statusbar + ui/ small shared components + src-tauri/ host (Rust) + src/ + engine/ discovery, data folder, port selection, supervisor, job object, watchdog + connection/ Connection trait, LocalConnection, safety mode, agent channel + query/ pg wire session, statement splitting, results, explorer statements + agent/ MCP client, approvals, InferenceBackend trait, backends, loop, ACP client, delegated agent, what a model is told about presentation, the turn log + secrets/ keychain access + activity/ operator history, engine audit log reader + icons/ provider icon lookup, fetch and cache + library/ the query library's index and documents, fetch and cache + config/ settings + ipc/ command and event definitions, saving an export, the app's own links + applog.rs the app's own log + webview_runtime.rs the page renderer on Windows: using one shipped beside the app, and the dialog shown when there is none + .cargo/ build flags: the C runtime linked in on Windows + examples/ pgwire_spike and mcp_spike, the probes behind the spike reports + tests/ integration tests against a real stackql + scripts/ test launcher, the check of what a Windows executable asks the system for + docs/ design notes and spike reports +``` + +Only `src/host/` may import Tauri APIs. Panes call the typed wrappers in that directory. + +## Commands + +These commands all pass on Windows. Run them from the repository root unless noted. + +``` +npm install +npm run tauri dev +npm run lint +npm run typecheck +npm test + +cd src-tauri +cargo fmt --check +cargo clippy --all-targets -- -D warnings +cargo test +``` + +Other commands that are useful: + +``` +npm run format format the webview sources +npm run tauri build -- --no-bundle release build of the executable, no installer +npm run tauri build -- --debug --no-bundle the debug build CI runs +cd src-tauri && cargo run --example pgwire_spike rerun the pg wire probe +cd src-tauri && cargo run --example mcp_spike rerun the MCP probe +npm run tauri build -- --target universal-apple-darwin --bundles app,dmg on a Mac, the test build CI keeps +``` + +Things to know about them: + +- `npm run lint` runs ESLint and then `prettier --check`. +- `npm test` goes through `scripts/test.js`. Vitest fails on Windows when the working directory is spelled with a lower-case drive letter, which an editor terminal can do. The launcher corrects that. +- `cargo test` includes integration tests that start a real `stackql`. They are skipped, with a note on stderr, when no binary is found. They need no credentials and no network. +- The release executable is `src-tauri/target/release/stackql-workbench.exe` on Windows. +- The engine's `--approot` is `.stackql` beside the Workbench executable. For a build from this repository that is `src-tauri/target/release/.stackql`, or `target/debug/.stackql` under `npm run tauri dev`. Where that folder cannot be written to, the fallback is `/engine`, which on Windows is `%APPDATA%\io.stackql.workbench\engine`. The operator can name another folder in Settings. +- Settings are in `/settings.json`. The agent audit log is in `/audit` and the operator's statement history in `/history.jsonl`. Those two do not move with the engine's data folder. +- The app's own log is in `/logs`, one file for each run, named `stackql_workbench_.log`. The host writes it and nothing reads it back. It is apart from the engine's audit log, which the engine writes. The 20 newest files are kept. +- The binaries are built to need nothing from the system that has to be installed. The maintainer asked for that on 19 November 2026. + - Windows: the C runtime is linked in whole, with `+crt-static` in `src-tauri/.cargo/config.toml`. Tauri's own default links the Visual C++ runtime in and leaves the Universal C runtime to Windows, and it would undo the flag for that part, so `build.windows.staticVCRuntime` is `false` in `tauri.conf.json`. Keep the two together. `node scripts/check-exe-imports.js ` reads the import tables and fails on a runtime library. With `x64` or `arm64` after the path it also fails when the executable is built for another processor. CI runs it on each optimised build. + - macOS: the app links only to system frameworks and libraries under `/usr/lib`. CI checks that with `otool`. CI also checks that the bundle declares the macOS version in `tauri.conf.json` as its minimum and that both architectures are built for it. + - The WebView2 runtime is the one thing a Windows executable cannot carry. `webview_runtime.rs` uses a runtime in a `WebView2Runtime` folder beside the executable when there is one, by setting the loader's variable before anything else runs, and the system's runtime otherwise. Which was used is in the app's log. A runtime beside the app wins over a variable that was already set, the same rule the engine follows. + - The installers do not ship that folder, so the system's runtime is the normal case. Microsoft says the runtime is included as part of Windows 11 and is on the vast majority of Windows 10 devices. Where there is none, the app says so before it starts anything. `webview_runtime::require` asks the question Tauri asks before it makes a window. Where the answer is no it shows a dialog of the system's, "StackQL Workbench requires the Microsoft Edge WebView2 Runtime", with a link to Microsoft's page, and exits. The maintainer asked for that on 20 November 2026, in place of any change to the installer. Without it the app ends in a panic, behind a dialog of Tauri's that names no app. + - The dialog says that line and one sentence more: "See" the address "for installation instructions." The maintainer asked for it to be that short. It does not say what the runtime is for or where it was looked for, and it is the same whatever the reason no runtime could be used. Do not add to it. + - A debug build is a console program, so a terminal opens with it, and with this dialog. The optimised build is a windowed program and opens none. +- To run a build beside an installed copy without sharing its settings, history and logs, give it another identifier: `npm run tauri build -- --debug --no-bundle --config ` with a file that holds `{ "identifier": "io.stackql.workbench.dev" }`. The app data and config directories are named after the identifier. +- One test writes and removes a throwaway entry in the real OS keychain. It skips itself where no keychain can be opened. +- An editor's language server can build in the same `target` directory and hold a file the build needs, which shows up as linker error `LNK1104` on Windows. Running the command again clears it. + +## Engine interface + +The facts in this section were read from `stackql` `main` in November 2026, and the `srv` facts were then tested against `stackql` v1.0.888. The evidence is in `docs/spike-pgwire.md`. Confirm against `stackql --help` for the installed version. The reference docs are `docs/mcp.md` and `pkg/mcp_server/README.md` in the stackql repository. + +### Discovery + +Resolve the `stackql` binary in this order and stop at the first hit. + +1. Explicit path in settings +2. The engine installed with the app +3. `STACKQL_BIN` environment variable +4. Well-known install locations for the platform +5. `PATH` + +Show the resolved path and version in the UI. If nothing is found, say so plainly and point at the settings field. + +The engine installed with the app is the default. The maintainer decided that on 19 November 2026, for the MSI and then for macOS: the installers ship the two together, and that pair is the one built and tested together. Only a path in settings comes before it, because that is a choice the operator can only make after the install. `STACKQL_BIN` used to come second. It now comes after, since a variable can be older than the install and would swap the engine without anyone choosing that. When the variable is set and passed over, the status says so, and a variable that points nowhere does not stop the installed engine from starting. + +What "installed with the app" means differs by platform, because the installers lay the pair out differently. + +- Windows: `stackql.exe` in the same folder as the Workbench executable. That is where the MSI puts it. +- macOS: for an app that runs from a bundle, an engine inside the bundle beside the executable, and failing that `/usr/local/bin/stackql`, which is where the PKG puts the command. The PKG does not put an engine inside the bundle today. If a later one does, that one is found first. +- A build from this repository has no engine beside it and, on macOS, is not in a bundle. It has no installer behind it, so there the variable is still the next thing tried. + +On an Intel Mac the common package manager also links its `stackql` into `/usr/local/bin`. The app cannot tell that one from the PKG's. Whichever is at that path is taken as the installed engine, as it was the first place looked before this change. + +The two explicit sources are strict when they are reached. If the settings path is set and does not point to a file, or `STACKQL_BIN` is the source in turn and does not, that is an error and the search stops there. Running a different binary than the one the operator named would be worse than stopping. + +### Process lifecycle + +One supervisor owns every child process. + +- Children must not outlive the app, including after a crash or force quit. Use a job object on Windows, created with kill-on-close. On macOS a process group is not enough on its own, because nothing signals the group when the app receives SIGKILL. Each child therefore also gets a watchdog: `/bin/sh` blocked on a pipe that only the app holds open, which signals the group when the pipe closes. +- On Windows a child can start out in a job of its own. A packaged app does, and a program on `PATH` can be an alias for one. Such a process cannot join a job that already has members, so it gets a kill-on-close job to itself. An empty job always takes it. +- The watchdog script must stay POSIX. `kill -s TERM -- -PGID` works in every `/bin/sh` tried. `kill -TERM -- -PGID` does not. +- Start console children with `CREATE_NO_WINDOW` on Windows, otherwise a console window flashes up. +- Wait for readiness with a timeout. Surface failures in the UI with the captured stderr. +- The port is chosen first and given to the engine after, and something else can take it in between. The engine then exits at once, with exit code 0. The host starts it again on a fresh port, up to three times, before it reports a failure. An engine that is running and does not answer is not started again. This showed up in CI, where tests start engines side by side. +- Capture stderr of every child. For a stdio MCP process, stdout carries protocol frames only. + +### `stackql srv` (human channel) + +The explorer and the editor use this channel. Every point below was tested. See `docs/spike-pgwire.md`. + +Flags the host passes: + +- `--pgsrv.address 127.0.0.1`, always. The default is `0.0.0.0` and the listener has no authentication. +- `--pgsrv.port` with a free port chosen by the host. The default is 5466 and may be taken. +- `--approot` with the engine's data folder, always. The engine's own default is `.stackql` in the working directory, so the provider cache would otherwise follow wherever the app was started from. The host resolves the folder in this order and stops at the first hit. + 1. Explicit folder in settings. This source is strict: a folder that is not a full path, or cannot be created or written to, is an error and the engine does not start. + 2. `.stackql` beside the Workbench executable. Skipped inside a macOS app bundle, because adding a file to a signed bundle breaks its signature. + 3. `/engine`. Used when the folder beside the executable cannot be written to, which is the normal case for an app installed under `Program Files`. The settings pane says so. +- The Workbench does not share the operator's own `.stackql` folder unless they point it there. +- `--pgsrv.debug.enable`. Without it an upstream API failure is an empty, successful result with the reason only on stderr. With it the reason arrives as a pg notice on the connection that ran the statement. +- `--env.file` when the operator has set a credentials file. + +How the server behaves: + +- Simple query protocol only. The extended protocol does not work through `tokio-postgres`. Statements are never parameterised. +- One statement per message. The server runs the first statement in a message and silently drops the rest, so the host splits editor text and sends statements one at a time. It also cuts at a semicolon inside a string literal, which the host cannot work around. +- Every value is text. Type OIDs carry no information. A SQL NULL arrives as an empty string. +- The command tag has no row count. The host counts rows. +- Rows do not stream. They all arrive when the statement finishes. +- There is no cancel. A cancel request has no effect and closing the connection does not stop the work. The UI offers "stop waiting" and says the statement may still complete. Restarting the engine is the only way to stop a statement. +- Errors carry a severity, the code `XXUUU` and a message. Nothing else. +- Notices accumulate on a connection and are sent again with every later statement. The host reports only the newly appended text on the long-lived editor session. +- Readiness: connect and run `SHOW VERSION`. The engine is ready about 100 ms after spawn. Give each connect attempt its own short timeout, because Windows retries a refused loopback connect for about half a second. + +How the host uses it: + +- The editor has one long-lived session. Each explorer statement gets its own short-lived session. +- The explorer is built from metadata statements: `SHOW PROVIDERS`, `SHOW EXTENDED SERVICES IN`, `SHOW EXTENDED RESOURCES IN`, `SHOW EXTENDED METHODS IN`, `DESCRIBE EXTENDED` and `DESCRIBE METHOD EXTENDED`. Results are mapped by column name, not position. +- Identifiers are validated and written in double quotes. This engine version rejects backticks. Never build statements by raw string interpolation of UI input. +- A zero-row result that comes with a notice is shown with the notice beside it, not as plain "no data". The notice is what the provider answered. The UI passes it on and does not rule on it. See Provider errors and empty results. + +### `stackql mcp` (agent channel) + +Only the agent runtime uses this channel. Every point below was tested. See `docs/spike-mcp.md`. + +How the host starts it: + +- `--mcp.server.type=stdio`, always. The default transport is HTTP. +- `--approot` with the same directory `srv` uses, and `--env.file` when the operator has set a credentials file. +- Configuration is inline JSON through `--mcp.config`. The host sets `server.transport`, `server.mode`, `server.request_timeout` and `server.audit`. +- `server.audit.file.dir` is a directory under the app data directory, otherwise the log lands in the working directory. The log is JSONL, one record per tool call, one file per server start. The activity pane reads it. +- `server.request_timeout` is raised from its 30 second default, which a paged provider query can exceed. + +How the server behaves: + +- Every protocol revision the SDK offers is negotiated. The host offers `2025-11-25`, the newest one with an `initialize` handshake. On it the approval prompt is a server-initiated elicitation, the simpler of the two approval flows. +- 15 tools. Each result carries rendered text for the model and a structured payload. Row results are `{ "rows": [...] }`, which the host turns into a table for the grid. Nothing needs to be set to get JSON: the structured payload is always there. +- The handshake returns about 25,000 characters of guidance for the model. The host puts it in the system prompt. +- A provider call that fails comes back as a tool error: `upstream http error: {"http_status": 401, "retryable": false}: ...`. A lookup that finds nothing comes back as an empty result with no error, and what the provider said is on the server's stderr. The server's instructions tell a model how to read each. The host shows the stderr line to the operator beside the tool result and adds nothing to what the model receives. See Provider errors and empty results. +- A statement the server cannot parse is classed `unknown` and asks for approval, even through the read tool. +- Every tool carries hints. The tools that take no SQL say they are read-only. The SQL tools never claim that, because what they do depends on the statement, but each says whether it can make a destructive change: `run_mutation_query` and `run_lifecycle_operation` can, the rest cannot. +- One server runs tool calls at the same time. Four single-request statements sent together were answered in about the time of one. +- The server exits when its stdin closes. + +How the host uses it: + +- The connection supplies the two byte streams. The agent runtime never spawns the process itself, and the supervisor owns it like any other child. +- One session is kept per safety mode. Changing the mode opens a new session, because the mode is fixed when the server starts. +- For a delegated agent the connection starts the agent instead, and tells it how to start the MCP server in the workspace safety mode. The agent is then the MCP client. See Inference. + +The workspace safety setting maps directly onto `server.mode`. + +| Mode | SELECT and metadata | INSERT, UPDATE, REPLACE | DELETE | EXEC | +|---|---|---|---|---| +| `read_only` | allow | refuse | refuse | refuse | +| `safe` (default) | allow | needs approval | needs approval | needs approval | +| `delete_safe` | allow | allow | needs approval | needs approval | +| `full_access` | allow | allow | allow | allow | + +"Needs approval" is implemented with MCP elicitation. The host's MCP client must advertise the elicitation capability, otherwise gated tools are refused. The approval card in the UI is the answer to the server's `elicitation/create` request. Show the exact SQL on the card. Never auto-accept. + +The request is a form with no fields. Its message holds the tool, the query class and the SQL. The host waits for the operator for as long as it takes. With nobody listening the answer is decline, and stopping the turn answers cancel. + +### Provider errors and empty results + +Where this is handled was decided by the maintainer on 18 November 2026: in the engine, not in this app. Do not add logic for it here. + +- On the agent channel the engine's MCP server already handles it. It runs statements with strict upstream errors, so a provider call that fails is a tool error carrying the status and whether a retry can help. A lookup that finds nothing is an empty result, because "not found" is a valid answer. The server's instructions tell a model how to read each. They are in `pkg/mcp_server/content/instructions/06-errors.md` in the stackql repository. +- That was checked against v1.0.888 with no provider credentials in the environment. A call that needs a sign-in returned the tool error. A list for an owner that does not exist returned no rows. +- On the human channel `srv` answers a provider call that returned nothing with an empty, successful result, and with `--pgsrv.debug.enable` a notice carries what the provider said. That stays. The server cannot fail a statement because a lookup found nothing, and the engine reaches providers over more than one protocol, gRPC among them. +- This app passes on what the engine says and adds nothing. It does not sort a provider's answer by status code, does not call an answer a failure, and does not add to or change what a model is told about a result. If something seems to need that, the change belongs in the engine's MCP server. +- Leaving a failed call out of the conversation is a matter of display, decided by the maintainer on 19 November 2026. The model still receives the engine's error exactly as the engine sent it, and the host writes it to the app's log. A call counts as failed when the engine, or the agent, said it failed. Nothing in the app works that out. +- An earlier version of this file, and of `docs/spike-mcp.md`, said the MCP server hides provider failures from the model. That was wrong. It came from testing one lookup that found nothing and taking it for every kind of failure. Test more than one case before recording an engine behaviour, and read the engine's source when it is to hand. + +### Credentials + +Provider credentials are environment variables read by the engine. The app never parses or displays their values. + +- Apps launched from Finder or the Dock on macOS do not inherit shell profile exports. Do not rely on the app's own environment. +- The host builds the child environment explicitly. Values come from the OS keychain and are injected at spawn, or from an operator-supplied dotenv file passed with `--env.file`. +- Until the keychain store for provider credentials exists, the engine starts with the app's own environment as the base, plus the `--env.file` from settings. That works on Windows, where the app sees the user's environment variables. On macOS the env file is the dependable route. +- The MCP `reload_credentials` tool re-sources `--env.file`. `stackql srv` needs a restart to pick up changes. +- The UI shows variable names and whether they are set. Never log or display environment contents. + +## Inference + +Backends are built in this order. + +1. API key. Gemini first because it works on the free tier, then Anthropic, OpenAI and any OpenAI-compatible base URL, which covers local inference. The host runs the loop and owns the MCP client. +2. ChatGPT plan sign-in through OpenAI's Sign in with ChatGPT programme. This needs a client ID issued to this project. Do not start it until the maintainer confirms the client ID exists. +3. Delegated. An ACP agent that the operator has installed and signed in to themselves. In this mode the agent is the MCP client and spawns its own `stackql mcp`. Each agent needs its own launcher, because how the engine's MCP server is handed over and how tools are restricted differs from one agent to the next. Verify an agent's elicitation handling before building on it, and record it in `docs/`. + +What exists now under item 1: + +| Backend | API | Default model | Notes | +|---|---|---|---| +| Gemini | `generateContent` | `gemini-4-hydrogen` | The model's reply is kept and sent back untouched, because function calls carry a signature that must be returned in place | +| Anthropic | Messages API over REST, since there is no official Rust SDK | `claude-opus-5-5` | Thinking blocks are returned untouched. For models that support it, server-side fallback on a declined request is switched on | +| OpenAI-compatible | Chat Completions | none, the operator names it | Covers local inference. Some of OpenAI's newest models take tool calls only through its Responses API, which is not implemented | + +How they are built: + +- A backend turns the shared conversation into one request and the reply back into text and tool calls. It holds no state. The loop, the MCP client and the approval flow are the same for all of them. +- Each keeps the provider's own form of a reply and replays it as it was. Do not rebuild a reply from its parsed parts. +- No sampling parameters are sent. Current models from all three providers ignore or reject them. +- Replies are not streamed. A turn shows progress per tool call. +- The tool calls of one reply run at the same time when the engine marks the tool as not destructive, with `destructiveHint: false`. That covers its query and discovery tools. A tool the engine marks as destructive, or one that carries no hint, runs alone and in the model's order, so what follows a change sees the change. The host takes the engine's word for this and reads nothing into the statement. Results go back to the model in the order it asked. +- More than one approval prompt can be open at once. A prompt is shown on the tool call that sent the statement. +- The API key is read from the keychain when a turn starts. Settings hold the backend, the model and the address, never the key. +- Every backend reports what a call used in the same three counts: the whole input, the part of it read from the provider's cache, and the output, with the model's thinking where the provider counts it. The host adds them up over the calls of a turn. A count a provider does not send stays unknown and is not turned into zero. +- A model is told how its work is shown, and how to ask for a chart, by one text in `agent/guidance.rs`. The host's loop puts it in the system prompt ahead of the engine's guidance. A delegated agent gets it with the first message. It is about presentation only, which is this app's to say because drawing is this app's capability. It says nothing about how a result is to be read. A test holds it to that. + +What exists now under item 3 is the GitHub Copilot CLI. Every point was tested. See `docs/spike-acp.md`. + +- The host starts `copilot --acp` under the supervisor and speaks ACP version 1 to it over stdio. +- The engine's MCP server is named in a file passed with `--additional-mcp-config`, under the name `stackql`. The CLI rejects a stdio MCP server passed in `session/new`, and then silently uses the operator's own Copilot configuration, so that route must not be used. +- `--available-tools` lists the engine's tools, read from the engine at start. The model then has no shell, no file access and no other MCP server. `--allow-tool=stackql` stops the CLI asking about each engine tool call. +- The workspace safety mode is passed to the engine as for the other backends. The CLI does not relay MCP elicitation, so the engine refuses a statement that needs approval instead of asking. It fails closed. Do not put a gate of the host's own in its place. +- A `session/request_permission` from the agent is declined and the operator is told. None is expected, and one means the agent is reaching for something outside the engine. +- The model is chosen with `session/set_config_option`. Empty leaves the CLI's own choice. The settings pane lists the models with what each costs against the operator's plan. +- The CLI reports what a turn used in the answer to `session/prompt`, and the host passes that on. It is not what the operator pays, since the plan is billed by the request. The CLI also sends `usage_update` with how full the model's context window is, which the host does not use yet. +- The engine's stderr goes to the CLI, so the operator is not shown what a provider said when a lookup found nothing. Errors are not affected: they come back as tool errors on this path as on the other. +- Subagents can be allowed, as a setting that is off by default and marked experimental. With it on, the CLI's `task` tool is added to `--available-tools`. A subagent gets the same tools as the agent that starts it, the engine's and `task`, and uses the same MCP server, so the same safety mode. That was tested: a subagent asked for a shell and for a file write had neither. +- They are off by default because they were safe and not dependable. In a real turn a small model reached for subagents when it was stuck on a large result, they nested four deep, and the turn was slower and its answer wrong. Do not turn them on by default without testing that again. +- The first prompt tells the agent when to use subagents: independent lookups across providers, services or resources, never a change. That direction lives here because starting agents is the client's capability. The engine cannot start one. +- A subagent's tool calls carry its id under `_meta["github.com/copilot"]`. The host marks each call with the subagent's name, shows the start of a subagent with its task, and keeps a subagent's own message text out of the conversation. A turn is stopped when a subagent starts a subagent of its own, and when more than 12 are started. The CLI itself stops nesting at depth four. +- The CLI has three kinds of subagent. `general-purpose` has the engine's tools and runs on the session's model. `task` has them and runs on a model the CLI picks, `gpt-6-luna` when tested. `explore` has none of the engine's tools. None of the three has a shell or file access under this tool list. The first prompt asks for `general-purpose` in `sync` mode and rules out `explore` and background mode. That advice is in the Copilot profile, not in the general guidance. What subagents cost was not measured. + +These rules hold for every backend. + +- Never reuse, read or proxy another product's OAuth credentials or client IDs. That includes Claude Code, Gemini CLI and Codex. Never add a vendor login button without a client ID issued to this project for that purpose. +- API keys and tokens live in the OS keychain. Never in settings files, logs, the webview or `localStorage`. +- The model never sees credentials. Tool results are the only engine data it receives. + +## UI notes + +A few fixed points for the interface. + +- Brand colour is Classic Blue, `#0F4C81`. It is the primary colour: primary buttons, the selection, links, focus rings, the tab in front and the wordmark. There is no second blue. The lighter and darker blues are steps of it, kept as tokens. +- Every colour is a token in `src/styles.css`. A component names a token and never a colour value. The dark theme applies when the root element carries `data-theme="dark"`. That follows the system setting unless the operator picks Light or Dark under View, and the pick is kept in the webview's local storage. +- A test reads the stylesheet and checks each pair of text and surface against WCAG AA, 4.5 to 1, in both themes. A token change that breaks a pair fails the test. +- The StackQL wordmark heads the side menu. Its outline is `static/img/logo-original.svg` from `stackql/stackql.io`, drawn in the accent colour so it follows the theme. +- The status bar is neutral. A coloured dot carries the engine's state. +- The app icon is StackQL's own favicon. The files in `src-tauri/icons/` were generated with `npx tauri icon` from `static/android-chrome-512x512.png` in the `stackql/stackql.io` repository, which is the same mark as its `favicon.ico` at a usable resolution. +- Provider nodes in the explorer show the provider's own icon. The host resolves it through the provider dictionary published at `src/configs/providers.json` in `stackql/stackql.io`, fetches the icon from `stackql.io`, caches it in the app cache directory and passes it to the webview as a `data:` URL. A provider with no entry, or whose icon cannot be fetched, shows the letter badge. Providers built into the engine, such as `stackql_preview`, show the StackQL icon, which is compiled in. The webview itself still makes no network calls. A snapshot of the dictionary is compiled in as a fallback. +- The Library view lists the query library for the operator. The host reads it from the `stackql/query-library.stackql.io` repository on `raw.githubusercontent.com`: the index at `static/docs/query-library/index.json`, and one markdown document for each entry under `query-library/queries`. Both are kept in the app cache directory, and an older copy is shown, and marked, when the library cannot be reached. The webview still makes no network calls. The MCP library tools are the agent's and are not used here. +- An entry's id is checked before it is put in an address. A document's front matter is taken off, not parsed, and the rest is drawn by the same markdown reader as a reply. The entry's statement is the first SQL block under its Query heading. +- A library statement is a template, with `{{name}}` where a value goes. It opens in a new tab under a comment that names the entry and what to fill in. The app fills nothing in and runs nothing. +- Entries are grouped by use case, which is the first of the entry's own tags that names one. By default only entries whose providers are all installed are listed. +- Under an empty conversation one suggestion asks about metadata and the others come from library entries that can run here: stable, not a mutation, and for installed providers. With none, the earlier fixed suggestions are shown. +- Saved queries are plain `.iql` files on disk, not an app database. +- Layout: a menu bar with File, Edit, View, Query, Providers and Help, a side menu, one main view at a time, and the status bar. The views are chat, the explorer with the editor and results, the query library, and activity. Settings is a dialog. Chat is the view the app opens in. +- The menus are drawn in the webview, not by the OS, so they are the same on both platforms and can be tested like the rest of the page. They repeat what the side menu and the panes offer. +- Every view stays mounted while another is shown, so the editor keeps its text and history and a running turn keeps its place. +- A turn is shown as its answer. The layout is worked out in `src/lib/conversation.ts`, and `docs/charts.md` describes it. + - What the assistant did on the way is one list of steps above the answer: each call with its SQL and its result, and what the assistant wrote before going on to another call. The list is open while the turn runs and folded away when it ends. It is always open while a call waits for the operator's decision. + - A call that failed is not listed, and its error text is drawn nowhere. The host writes it to the app's log. Help > Show Log File shows the file. The Activity view still lists every statement the agent ran, with the engine's decision. + - A call the operator was asked about stays in the list whatever became of it. If they approved it and it then failed, the step shows why, because the outcome of their own decision is theirs to see. + - A turn that fails as a whole, for example on a rejected API key, still says so in the conversation. + - What the turn used, in tokens, is said on the line that heads the steps once the turn has ended, small and to the side: tokens in, the part of them the provider read from its cache, and tokens out. A turn with no steps says it on a line of its own in the same place. It is the provider's own count, added up over every call to the model in the turn, and is never estimated: a count that was not reported is left out. `docs/charts.md` says where each backend's counts come from. + - The last statement of the turn that returned rows is shown under the steps as a table, with the statements the assistant asked for in the same step, up to four in all. An answer that holds chart blocks is shown with those instead. The host marks each call with the step that asked for it. For a delegated agent, which does not say where a step ends, the calls that follow one of its messages count as one step. +- A result set in the conversation is a table of every row the host sent, in the same grid as the results pane. A click on a column sorts by it: ascending, descending, then the order of arrival. Numbers sort by size and empty values go last. The download control saves the rows as CSV, in the order shown, through the system's save dialog. The results pane sorts the same way. +- A model asks for a chart with a fenced block of the language `chart` that holds one JSON object. The format, where the rows come from, the limits and the mark rules are in `docs/charts.md`. + - The block is data. It is parsed, checked and drawn as SVG by components in this repository. Nothing in it is run and nothing a model writes becomes markup. + - The rows come from the most recent result set that has the columns the block names, or from the block itself. A block that cannot be drawn is shown as the text it is, with the reason. + - A chart and its table are two views of the same rows, one click apart. A chart has one value axis and at most eight series. + - The series colours are the tokens `--chart-1` to `--chart-8`, used in order and never cycled. The order keeps neighbours apart for colour-blind readers and was checked as a set in each theme. Do not add or reorder one by eye. +- Replies are read as markdown by a small reader in `src/lib/markdown.ts` that builds a tree. Model output is never turned into HTML. Links are shown and never opened. +- The only links the app opens are its own, from the Help menu and the About dialog: the documentation, the query library and the issue tracker. The webview names a link and the host holds its address, so nothing on a page can have an address opened. One more is opened with no webview at all: Microsoft's page for the WebView2 runtime, from the dialog the host shows when no runtime is found. The host holds that address too. +- Activity lists time, who ran it, the safety mode, the statement, the duration, the row count and the outcome, and can be narrowed by who and by outcome. For the agent the outcome is the engine's `decision` from its audit log, grouped for the filter and never worked out from the statement. The audit log has no row count and does not say which backend made a call, so agent rows show no count and are labelled "Agent". What is listed can be saved as JSONL. +- The status bar shows the engine state, its version and the pg wire address. A click on the address copies `postgres://stackql@127.0.0.1:/stackql?sslmode=disable`. The popover on the state holds the binary, the data folder and Restart. +- "Reload Credentials" in the Providers menu restarts the engine, and says so. On the human channel that is the only way credentials are read again. +- Under a method the explorer groups fields into Inputs and Outputs, both collapsed until opened. A field is an input when the engine's param type starts with `input`, and an output otherwise. +- The explorer does not list `stackql_preview`, the provider built into the engine. It is hidden for now and may come back. The name is in `HIDDEN_PROVIDERS` in `query/explorer.rs` and nowhere else. Only the tree leaves it out: `SHOW PROVIDERS` in the editor and the engine's answers to a model are not filtered. +- The explorer filter looks only at what has been loaded, and nothing is fetched on a keystroke. Starting a filter reads each provider's services, one statement for each provider. Enter reads the resources of every service not opened yet, four at a time, with progress, and Esc stops it. Methods are matched where a resource's methods have been opened. Under a filter at most 400 rows are drawn. +- A statement generated from the explorer opens in a new tab and does not run. It is a template built from what the engine reports for the method, with `` where a value is needed. `DESCRIBE EXTENDED` from the menu, and installing or updating a provider, run on the human channel like anything else the operator runs, so they are in the history. +- A provider shows an update marker when `REGISTRY LIST` has a newer version than `SHOW PROVIDERS` reports. The engine asks the registry, so this needs the network. When it cannot be asked, no marker is shown. +- A method's SQL verb is drawn as a pill before its name, in one colour for SELECT and another for the rest. The colour follows the verb the engine reports and decides nothing. +- Nested JSON is common in results. The grid has a cell viewer for it, with pretty print and copy. +- Completion in the editor reads only what the explorer has loaded. It asks the engine for nothing, so a level that has not been opened in the explorer offers no names. After a keyword that takes a name, and after a dot, it offers the next level of provider, service and resource. Elsewhere it offers the fields of the resources the statement names. +- The statement history is the operator's own, from `history.jsonl`: statements only, each listed once, most recent first. A statement opens in a new tab, and runs only when the operator says so. +- A result is exported as CSV or JSON. The webview builds the text and the host saves it where the operator chooses in the system's save dialog. In JSON an object or an array is nested and everything else stays the text the engine sent, because the engine gives no types. +- "Copy as CLI" writes a `stackql exec` command with the full path of the binary and the engine's data folder, for PowerShell on Windows and a POSIX shell on macOS. The statement follows `--`, so one that starts with a comment is not read as a flag. In PowerShell a statement that holds a double quote goes through a temporary file, because the two PowerShell generations pass a double quote differently. The shapes are in `docs/spike-pgwire.md`. + +## Conventions + +Keep changes small and reviewable. + +- Rust: `cargo fmt`, clippy clean with warnings denied, no `unwrap` or `expect` outside tests, typed errors that serialise cleanly across IPC. +- TypeScript: strict mode, no `any`, ESLint and Prettier clean. +- Tests sit beside the code. Integration tests that need a real `stackql` are skipped when the binary is absent and must not need cloud credentials. Use metadata statements. +- Before building on an assumption about engine behaviour, test it against the real binary and record the finding in `docs/`. +- Justify every new dependency in the commit message. Prefer the standard library and the stack table above. +- Commit in small steps with conventional commit messages. Do not push, tag or open pull requests unless asked. +- Never commit secrets, `.env` files or audit logs. +- When a decision changes, update this file and `README.md` in the same commit. + +## Writing style + +This applies to docs, comments, commit messages and UI copy. + +- Plain ASCII punctuation. Use `-` where a dash is needed and `->` for arrows. No emojis. +- Matter-of-fact tone. No hyperbole and no marketing language. +- In markdown, put a sentence between a heading and any heading or table that follows it. +- Refer to other infrastructure-as-code tools in abstract terms. Do not name competing products in docs or UI copy. + +## Open questions + +Raise these with the maintainer when the work reaches them. Do not decide them alone. + +- How Workbench versions are pinned to engine releases, and the minimum engine version check at startup. +- How a build that ships is released from this repository: a tag and a release whose files the StackQL release fetches, in place of workflow artifacts that expire. +- Whether `srv` should later co-host the MCP server so the IDE and the agent share one engine session. +- Whether loopback pg wire needs TLS with a per-launch client certificate. + +These came out of the Copilot work. + +- Whether the Copilot CLI will relay MCP elicitation to an ACP client. Until it does there is no approval card on that path. +- Whether macOS should get a native menu bar in place of, or as well as, the one drawn in the webview. + +These came out of the two engine spikes and need an answer from the engine side. + +- `srv` has no cancel. It needs to send `BackendKeyData` and handle a cancel request before M1 can offer more than "stop waiting". +- `srv` runs only the first statement in a message, and cuts at a semicolon inside a string literal. +- Row objects from the MCP server lose the column order of the statement. + +The licence is decided: MIT, the same as `stackql`. + +Signing is decided too. The maintainer signs the Windows executable and the macOS app, and notarises the app, in the StackQL release that ships them. This repository signs nothing for release. + +So is the page renderer. The maintainer said on 20 November 2026 that the binaries are to stay small and run on most modern Windows and Mac machines, not carry a runtime of several hundred megabytes. The installers do not ship the WebView2 runtime, and the app uses the one Windows has. The `WebView2Runtime` folder beside the app still works for anyone who needs it. + +Three more were decided the same day. + +- Windows on Arm gets an executable built for Arm. The StackQL MSI is built for x64 and for arm64, and the maintainer said to build a native arm64 executable if emulation would not do. It would not: Windows emulates x64 only from Windows 11, there is no Arm machine here to try it on, and the arm64 MSI ships an engine built for Arm. CI builds and tests on GitHub's `windows-11-arm` runner, against the engine from `stackql_windows_arm64.zip`. Nothing is built across processors. +- The installer is not changed for the WebView2 runtime. The MSI adds the executable beside `stackql.exe` and nothing else: it neither ships the runtime nor installs it. The maintainer first chose an option in the MSI to install the runtime and then, the same day, chose this. Where the runtime is missing the app says so itself, in a dialog when it starts. Do not put an installer of the runtime in the host either. +- The oldest macOS the app supports is 13. `bundle.macOS.minimumSystemVersion` in `tauri.conf.json` is `13.0`, which goes into the bundle's `Info.plist` and sets the version the executable is built for. An older macOS refuses to open the app. The reason is the styling library, which needs the WebKit of Safari 16.4, from March 2023, and on a Mac the renderer is the WebKit of that macOS. Safari 16.4 came to macOS 13 in an update, so the first releases of macOS 13 have an older renderer and are still let in. diff --git a/README.md b/README.md new file mode 100644 index 0000000..fb1a0bf --- /dev/null +++ b/README.md @@ -0,0 +1,337 @@ +# StackQL Workbench + +Desktop query IDE and chat interface for [StackQL](https://github.com/stackql/stackql), for Windows and macOS. + +Status: pre-alpha. The query IDE foundations (M0), the core of chat (M3) and chat through the GitHub Copilot CLI work on Windows. Nothing here is released yet. On macOS the tests pass in CI and CI builds a test build, but the app has not been opened on a Mac. + +## Overview + +StackQL Workbench is a native desktop app that runs against the `stackql` engine installed on the same machine. It gives an operator two ways to work with cloud and SaaS providers as data sources accessed via SQL: a query IDE for statements they write themselves, and a chat interface in which a model proposes and runs statements under the engine's safety controls. + +The planned capabilities are listed below. + +- Provider explorer: a lazy tree of providers, services, resources, methods and fields +- Query library: the published library of working statements, grouped by use case, to open in the editor +- Query editor: tabs, StackQL-aware completion, saved `.iql` files +- Results grid: virtualised rows, sorting by column, JSON cell viewer, export +- Chat: the view the app opens in. It needs a model backend, and asks for one the first time a message is sent +- Answers with results: a turn is shown as its answer, with the result set as a table that sorts and downloads, and as a chart when one is asked for +- Approvals and activity: mutations proposed by a model wait for the operator, and every agent action is logged +- Settings: engine path, credentials profile, safety mode, inference backend + +## Architecture + +The app is a webview UI over a native host. The host owns every process, connection and secret. The webview is not served over HTTP and opens no network listener. + +```mermaid +flowchart TB + subgraph app["StackQL Workbench"] + ui["Webview UI
explorer, editor, results, chat, activity"] + subgraph host["Native host (Rust)"] + ipc["Typed IPC"] + query["Query service
pg wire client"] + agent["Agent runtime
MCP client, inference backends"] + sup["Supervisor
discovery, spawn, env, keychain"] + end + end + srv["stackql srv
pg wire on 127.0.0.1"] + mcp["stackql mcp
stdio"] + llm["Inference provider"] + cloud["Cloud and SaaS provider APIs"] + + ui <--> ipc + ipc --> query + ipc --> agent + ipc --> sup + query -->|pg wire| srv + agent -->|MCP over stdio| mcp + agent -->|HTTPS| llm + sup -.->|spawns| srv + sup -.->|spawns| mcp + srv --> cloud + mcp --> cloud +``` + +### Engine channels + +The host reaches the engine over two channels with different trust levels. They are kept separate on purpose. + +| Channel | Process | Transport | Used by | Statements come from | +|---|---|---|---|---| +| Human | `stackql srv` | Postgres wire protocol on 127.0.0.1 | Explorer, editor | The operator | +| Agent | `stackql mcp` | MCP over stdio | Agent runtime | A model | + +### Running a statement from the editor + +Statements the operator runs go straight down the human channel. Rows stream back to the grid in batches. + +```mermaid +sequenceDiagram + actor Operator + participant UI as Webview UI + participant Host as Host (query service) + participant Srv as stackql srv + participant API as Provider API + + Operator->>UI: Run statement + UI->>Host: run_query over IPC + Host->>Srv: Simple query on pg wire + Srv->>API: REST or GraphQL calls + API-->>Srv: Responses + Srv-->>Host: Row stream and notices + Host-->>UI: Row batches as events + UI-->>Operator: Results grid and history entry +``` + +### A chat turn with an approval + +Statements a model proposes go down the agent channel. The MCP server classifies each statement and, depending on the safety mode, asks the operator for approval through the host before running it. + +```mermaid +sequenceDiagram + actor Operator + participant UI as Webview UI + participant Agent as Host (agent runtime) + participant LLM as Inference backend + participant MCP as stackql mcp + + Operator->>UI: Chat message + UI->>Agent: send_message over IPC + Agent->>LLM: Messages and tool definitions + LLM-->>Agent: Tool call run_mutation_query + Agent->>MCP: tools/call + Note over MCP: Mode is safe and the statement is a mutation + MCP->>Agent: elicitation/create with the SQL + Agent->>UI: Approval card + Operator->>UI: Approve or decline + UI->>Agent: Decision + Agent->>MCP: Elicitation result + MCP-->>Agent: Tool result as JSON + Agent->>LLM: Tool result + LLM-->>Agent: Final answer + Agent-->>UI: Answer, rows in the grid, audit entry +``` + +### Safety modes + +The workspace safety setting is passed to the MCP server as `server.mode`. The engine does the classification and the gating; the app only renders the approval. + +| Mode | SELECT and metadata | INSERT, UPDATE, REPLACE | DELETE | EXEC | +|---|---|---|---|---| +| `read_only` | allow | refuse | refuse | refuse | +| `safe` (default) | allow | needs approval | needs approval | needs approval | +| `delete_safe` | allow | allow | needs approval | needs approval | +| `full_access` | allow | allow | allow | allow | + +### Inference backends + +Chat is optional. When it is enabled, the agent runtime talks to a model through one interface with several backends behind it. + +```mermaid +flowchart LR + rt["Agent runtime"] --> iface{{"InferenceBackend"}} + iface --> key["API key
Gemini, Anthropic, OpenAI, OpenAI-compatible"] + iface --> plan["Plan sign-in
Sign in with ChatGPT"] + iface --> acp["Delegated
ACP agent on this machine"] +``` + +The delegated backend that exists today is the GitHub Copilot CLI. It runs with the sign-in the CLI already has, which the app never sees, and it is given the engine's tools and nothing else. It cannot pass the engine's approval prompt on, so with it a statement that needs approval is refused instead of asked about. The findings behind this are in [docs/spike-acp.md](docs/spike-acp.md). + +The backends differ in how the operator signs in and in who runs the agent loop. + +| Backend | Sign-in | Agent loop | MCP client | +|---|---|---|---| +| API key | Key held in the OS keychain | Host | Host | +| Plan sign-in | Sign in with ChatGPT | Host | Host | +| Delegated | Whatever the installed ACP agent already uses | The agent | The agent | + +### Connections + +All engine access sits behind one interface. The first releases work only with the local engine. Connecting to a remote StackQL server comes later and does not change the UI. + +```mermaid +flowchart LR + panes["UI panes"] --> conn{{"Connection"}} + conn --> lc["LocalConnection
child processes on this machine"] + conn -.-> rc["RemoteConnection, later
pg wire with TLS, MCP over HTTP"] +``` + +## Credentials + +Provider credentials are environment variables read by the engine, as they are for the `stackql` CLI. The host builds the environment for the engine processes from values in the OS keychain or from a dotenv file the operator points at. The UI shows which variables are set and never shows their values. + +## Development + +These steps were run on Windows 11. + +Prerequisites: + +- Rust stable toolchain, 1.90 or later, from rustup +- Node.js LTS +- The [Tauri 2 prerequisites](https://v2.tauri.app/start/prerequisites/) for your platform +- A `stackql` binary on `PATH`, or its location in the `STACKQL_BIN` environment variable + +``` +npm install +npm run tauri dev +``` + +To build the executable without an installer: + +``` +npm run tauri build -- --no-bundle +``` + +On Windows that produces `src-tauri/target/release/stackql-workbench.exe`. + +Checks: + +``` +npm run lint +npm run typecheck +npm test + +cd src-tauri +cargo fmt --check +cargo clippy --all-targets -- -D warnings +cargo test +``` + +The integration tests start a real `stackql` and are skipped when none is found. They need no cloud credentials and no network. + +### Test build for macOS + +CI builds the app for macOS on every run and keeps the disk image as the workflow artifact `stackql-workbench-macos-universal`. It runs on Apple Silicon and Intel, on macOS 13 or later. It is for testing and is not a release: the signature is ad hoc, with no Developer ID, and nothing is notarised. + +To try it: + +- Download the artifact from the run's page on GitHub, which needs a GitHub sign-in, and open the disk image inside it. +- Drag the app to Applications. macOS refuses to open it the first time. Allow it under System Settings, Privacy & Security, with Open Anyway. The other way is `xattr -dr com.apple.quarantine "/Applications/StackQL Workbench.app"` in a terminal. +- Install the `stackql` CLI from the PKG on the [release page](https://github.com/stackql/stackql/releases/latest). Homebrew has v0.12.824, which is older than the v1.0.888 this app is built and tested against. The app looks in `/usr/local/bin`, where the PKG puts it, and then in `/opt/homebrew/bin`. If it is somewhere else, set its path under Settings. +- An app started from Finder does not see variables exported in a shell profile. For provider credentials, set a dotenv file under Settings. + +The same build on a Mac is `npm run tauri build -- --target universal-apple-darwin --bundles app,dmg`, after `rustup target add aarch64-apple-darwin x86_64-apple-darwin`. + +### What the installers take + +CI also keeps what the StackQL MSI and PKG are built from, on every run, as three more workflow artifacts. Each holds one file and its SHA-256. + +| Artifact | Holds | For | +|---|---|---| +| `stackql-workbench-windows-x64` | `stackql-workbench.exe`, the optimised build for x64 | The x64 MSI, which installs it beside `stackql.exe` | +| `stackql-workbench-windows-arm64` | `stackql-workbench.exe`, the optimised build for Arm | The arm64 MSI, which does the same | +| `stackql-workbench-macos-universal-app` | `stackql-workbench-macos-universal.app.tar.gz`, the app bundle for Apple Silicon and Intel | The PKG, which installs it to `/Applications` | + +Neither is signed for release. The Windows executable has no signature and the Mac app has an ad hoc one, so the StackQL release signs both, and notarises the Mac app, before it ships them. Unpack the Mac app with `tar -xzf`, which keeps the links and permissions inside the bundle. + +The StackQL MSI is built for x64 and for arm64, so there is a Windows executable for each. The two files have the same name, and the artifact says which is which. Each is built on a runner of that processor, and CI checks which processor the executable names. The maintainer asked for the arm64 build on 20 November 2026, in place of shipping the x64 executable to run under emulation: Windows emulates x64 only from Windows 11, it could not be tried here, and the arm64 MSI ships an engine built for Arm. + +Both are built to stand on their own, and CI checks that they do. + +- The Windows executable carries its C runtime inside it. What it asks the system for is Windows itself: `kernel32.dll`, `user32.dll` and the like. CI reads the import tables of the executable with `scripts/check-exe-imports.js` and fails the build if a runtime library is among them. +- The Mac app links only to what is part of macOS: system frameworks and libraries under `/usr/lib`. CI checks that with `otool`. + +One thing is not inside the Windows executable and cannot be: the page renderer, Microsoft's WebView2 runtime, which is a browser engine. The app uses the one Windows has. Microsoft says the runtime is included as part of Windows 11 and that the vast majority of Windows 10 devices already have it. It also says some devices may not, so there are two things to know. + +- Where no runtime is found, the app says so itself. It checks before it starts anything and shows a dialog of the system's: "StackQL Workbench requires the Microsoft Edge WebView2 Runtime", with a link to Microsoft's page for installation instructions. It exits when the dialog is closed, and starts as usual once the runtime is there. +- The installers are left out of it. The MSI adds the executable beside `stackql.exe` and nothing else: it neither ships the runtime nor installs it. The maintainer decided that on 20 November 2026. + +Shipping the runtime was ruled out the same day: the binaries stay small and run on most modern machines. For a machine that must rely on nothing from the system there is still a way, which is to put Microsoft's Fixed Version runtime beside the app: + +- Get the Fixed Version runtime for the processor of the executable, x64 or arm64, from Microsoft's WebView2 download page. It comes as a `.cab` to unpack. +- Install the unpacked folder beside `stackql-workbench.exe`, renamed to `WebView2Runtime`. + +When that folder is there the app uses it and does not look at what the system has. When it is not, the app uses the system's runtime. Nothing else is configured, so the same executable serves both. The folder is large: the runtime installed on the machine this was measured on is 878 MB in 918 files. It is also a browser engine at one fixed version, so a security update to it means a new installer, where the system's runtime is kept up to date by Windows. The app only ever loads its own pages from inside the executable, which limits what an out-of-date renderer is exposed to. macOS has nothing of the kind to ship, because its renderer is part of the system. That renderer is as old as the macOS it is on, so the app needs macOS 13 or later. The maintainer decided that on 20 November 2026. The bundle declares it as its minimum, and an older macOS refuses to open the app. The reason is the styling library the pages use, which needs the WebKit of Safari 16.4, from March 2023. Safari 16.4 came to macOS 13 in an update, so a Mac that is still on the first releases of macOS 13 opens the app with a renderer older than that. + +To fetch them from the latest run on `main`: `gh run download --repo stackql/stackql-workbench --branch main --name stackql-workbench-windows-x64`, and the same with the other names. GitHub keeps a workflow artifact for 90 days. A build to be shipped should come from a tagged release, which this repository does not make yet. + +### Using the app + +The engine keeps its provider cache in a folder of the app's own: `.stackql` beside the executable, or the app data directory when that place cannot be written to, as under `Program Files`. A first run therefore lists no providers. Run `REGISTRY PULL github;` in the editor to install one. To use another folder, for example the `.stackql` folder you already use with the `stackql` CLI, set it under Settings. + +Provider credentials are environment variables the engine reads. On Windows the engine sees the variables of your user account. To use a dotenv file, set it under Settings. + +The app opens in chat. The side menu leads to the explorer, which holds the provider tree, the query editor and the results grid, to the query library, and to the activity list. The File, Edit, View, Query, Providers and Help menus repeat those. + +Chat needs a model backend. The first time you send a message without one, the model backend settings open. There are two kinds. + +- GitHub Copilot: uses the Copilot CLI installed on this machine and the sign-in it already has. Install the CLI, run `copilot login` once, then choose GitHub Copilot. Requests count against your Copilot plan, and the settings list each model with what it costs. There is an experimental setting that lets the agent hand the parts of a request that spans several providers to subagents. It is off by default. +- An API key for Gemini, Anthropic, or an OpenAI-compatible server, which covers local inference. The key goes to the operating system keychain. + +With an API key backend, independent queries the model asks for in one step run at the same time. + +A turn is shown as its answer. What the assistant did on the way, the calls it made with their SQL and results, is a list of steps above the answer that folds away when the turn ends. The result set the answer rests on is shown as a table: click a column to sort by it, and use the download control to save it as CSV. Ask for a chart, a plot or a trend and the assistant draws one from the result: bars, a line, an area, a pie or a scatter chart, with the table of the same rows one click away. + +When a turn ends, the line that heads its steps says what it used in tokens, as the provider counted it: tokens in, how many of those were read from the provider's cache, and tokens out. The counts cover every call to the model in the turn. With GitHub Copilot they say how large a turn was, not what it cost, since that plan is billed by the request. + +A statement that fails on the way to an answer is not listed in the conversation. The assistant corrects it and carries on. Each one is written to the app's log with what came back, and Help > Show Log File opens it. The Activity view still lists every statement the assistant ran, with its outcome. + +Without a backend the explorer and the query editor work as before. + +## Repository layout + +The layout is shown below. + +``` +stackql-workbench/ + src/ webview (React) + host/ typed wrappers over IPC + lib/ pure logic with tests + state/ hooks that connect the host to the panes + panes/ shell, chat, explorer, editor, results, library, activity, settings, statusbar + ui/ small shared components + src-tauri/ host (Rust) + src/ + engine/ discovery, supervisor, process lifecycle + connection/ Connection trait, LocalConnection + query/ pg wire client, statement splitting, results + agent/ MCP client, approvals, backends, loop, ACP client, delegated agent + secrets/ keychain access + activity/ operator history and the engine audit log + icons/ provider icons + library/ the query library + config/ settings + ipc/ command and event definitions + applog.rs the app's own log + examples/ the probes behind the spike reports + tests/ integration tests against a real stackql + docs/ design notes and spike reports +``` + +What the engine actually does on each channel is recorded in [docs/spike-pgwire.md](docs/spike-pgwire.md) and [docs/spike-mcp.md](docs/spike-mcp.md). What the Copilot CLI does as a delegated agent is in [docs/spike-acp.md](docs/spike-acp.md). How a model asks for a chart, how a turn is laid out and what the app's log holds are in [docs/charts.md](docs/charts.md). + +## Roadmap + +Milestones are delivered in order where they depend on each other. Each one leaves the app in a usable state. M0 is done, and the core of M3 was built ahead of M1 and M2 so that both the IDE and chat could be tried together. The first delegated agent from M5, the GitHub Copilot CLI, is also in. Most of M1 is in: tabs, completion, the JSON cell viewer, history and export. Saved `.iql` files, cancel and a streaming grid are not. Chat also shows a turn as its answer, with charts and a sortable result table, which was not in the first plan for M3. + +| Milestone | Scope | +|---|---| +| M0 Foundations | App scaffold, engine discovery and supervision, pg wire spike, provider explorer, single editor and results grid, CI on Windows and macOS | +| M1 Query IDE | Editor tabs, completion from provider metadata, streaming grid with JSON cell viewer, cancel, history, saved `.iql` files, export | +| M2 Packaging | Signed artefacts consumed by the StackQL MSI and PKG builds, version pinning, first IDE-only release | +| M3 Chat | Agent loop, stdio MCP client with approvals, activity pane, Gemini API key backend, inference settings | +| M4 More backends | Anthropic, OpenAI and OpenAI-compatible keys, Sign in with ChatGPT | +| M5 Delegated agents | ACP backend for agents already installed on the machine | +| Later | Remote connection to a StackQL server | + +## Packaging + +StackQL Workbench has no installer of its own. It ships inside the StackQL installers, beside the `stackql` binary. + +- Windows: the StackQL MSI installs `stackql-workbench.exe` next to `stackql.exe` and adds a Start Menu entry. The executable needs no runtime installed. The page is drawn by the Microsoft WebView2 runtime that Windows has, which is part of Windows 11 and already on most Windows 10 machines. The MSI neither ships it nor installs it. Where it is missing the app says so when it starts, with a link to Microsoft's page. See "What the installers take". +- The app uses the `stackql` it was installed with: on Windows the one that sits beside it, and on macOS the command the PKG puts in `/usr/local/bin`, or an engine inside the app bundle if the PKG ever puts one there. That is the pair that was built and tested together, so nothing on the machine replaces it except a path the operator sets under Settings after the install. A `STACKQL_BIN` variable does not, and when one is set the status bar says it is not used. Neither installer has anything to configure for this. +- Under `Program Files` the folder beside the app cannot be written to, so the engine keeps its provider cache in the app data directory. A first run lists no providers. +- macOS: the StackQL PKG installs `StackQL Workbench.app` to `/Applications` alongside the `stackql` CLI. +- Bundle identifier: `io.stackql.workbench`. +- This repository builds the per-platform artefacts. The StackQL release workflow consumes a pinned Workbench version. + +## Prior art + +Two earlier prototypes informed the layout and the API shape. Neither is used at runtime. + +- [stackql-playground](https://github.com/stackql/stackql-playground): a browser UI with an explorer tree, an editor and a results grid +- [stackql-middleware](https://github.com/stackql/stackql-middleware): an HTTP layer over `stackql srv` + +## Licence + +MIT, the same as `stackql`. See [LICENSE](LICENSE). diff --git a/docs/charts.md b/docs/charts.md new file mode 100644 index 0000000..7dfb34d --- /dev/null +++ b/docs/charts.md @@ -0,0 +1,134 @@ +# Chart blocks + +This note describes how a model asks the Workbench for a chart, and how the conversation shows a turn. The model is told the same in `src-tauri/src/agent/guidance.rs`. The block is read by `src/lib/chart.ts` and placed by `src/lib/chartLayout.ts`. Keep the three in step. + +## Why a block and not a tool + +Drawing is this app's capability. The engine cannot draw, and a delegated agent is held to the engine's tools and nothing else, so a chart tool of the host's own would not reach it. A fenced block in the reply works the same on both ways a turn runs, because both end in text the chat pane already reads. + +The block is data. It is parsed as JSON, checked, and drawn as SVG by this app's own components. Nothing in it is run, and nothing a model writes becomes markup: a title or a label goes on the page as a text node. + +There is no charting dependency. Bars, lines, areas, points and a ring cover what a result set from a provider needs, and drawing them here keeps every colour a token, so a chart follows the theme like the rest of the app. + +## The block + +A fenced code block with the language `chart`, holding one JSON object. + +```` +```chart +{"type": "bar", "title": "Issues created per month", "x": "month", "y": ["issues_created"]} +``` +```` + +The members are these. + +| Member | Meaning | +|---|---| +| `type` | `bar`, `line`, `area`, `pie`, `scatter` or `table`. `column` is read as `bar`, and `donut` as `pie` | +| `title` | What the card is headed with. Without it the card is named after the columns | +| `x` | The column along the horizontal axis, or the one that names the parts of a pie | +| `y` | One or more columns that hold numbers. One name may be given as text | +| `series` | A column whose values name the series, for rows that carry one. Then only the first `y` column is drawn | +| `stacked` | `true` stacks the bars of each position. Bars only | +| `horizontal` | `true` lays the bars down, which suits long names. Bars only | +| `xLabel`, `yLabel` | Titles for the axes | +| `columns` | For a table: the columns to show, in order | +| `data` | Rows given in the block, as a list of objects. See below | + +A `table` block needs none of `x` and `y`. It shows a result set as a table. + +## Where the rows come from + +A block names columns. The rows are found in this order. + +1. The `data` member, when the block has one. +2. The most recent result set in the conversation that has every column the block names. A name matches whatever its case, and a name written exactly as the result has it wins. + +So a model shapes the result with SQL, with `GROUP BY`, `ORDER BY` and column aliases, and then names its columns. It does not copy rows into the block. `data` is for when no one result set holds what is to be drawn, for example two results put together. + +A block whose columns no result set has is not drawn. It is shown as the text it is, with the reason above it. + +## How the values are read + +The engine sends every value as text. A chart reads numbers out of that text, and also `1,234` and `45%`. A value that is not a number is left out, and the chart says how many were. + +For a line, an area or a scatter chart the `x` column is read as time when every value is a year, a month, a day or a date with a time, and as a number when every value is one. Then the points are placed where they fall, so a month with no rows leaves a gap and does not sit next to its neighbour. A time with no zone is taken as UTC. Anything else is a name, and names are spaced evenly in the order of the rows. Bars always treat `x` as names. + +Rows that share a point are added together when the block names a `series` column, and so are the rows of one part of a pie. A pie leaves out amounts that are not above zero. + +## Limits + +These keep a chart readable. Where one applies, the chart says so under the plot. + +- At most 8 series or parts, which is the number of chart colours. With more, the 7 largest are kept and the rest are added together as `Other`. +- At most 200 bars standing up or 25 lying down, and 2,000 points on a line. The first are kept, so a model orders the rows before it draws them. The table view always has every row. +- At most 5,000 rows in `data`. + +A chart has one value axis. Two measures of different size belong in two charts. + +## What is drawn + +The mark specifications are fixed, so charts look alike. + +- A bar is at most 24 pixels thick, square at the baseline and rounded at its other end. Bars and stacked segments that touch are kept apart by a 2 pixel gap in the surface colour, not by an outline. +- A line is 2 pixels. Points are marked while there are 30 or fewer on a line. +- An area is the line with a wash of its colour at one tenth strength. +- Gridlines are solid hairlines at round values. Axis values are written in full under ten thousand and short above, one style for a whole axis. +- Two or more series get a legend. One series gets none, since the title names it. +- Text is drawn in the ink tokens and never in a series colour. + +The pointer finds a position, not a mark: the whole plot answers it, and the tooltip lists every series at that position. The arrow keys do the same from the keyboard. Every chart has a table view of the same rows one click away, which is also where a value is read without hovering. + +## Colours + +The eight series colours are the tokens `--chart-1` to `--chart-8` in `src/styles.css`, with a second set for the dark theme. They are used in order and never cycled. The first is a step of Classic Blue. + +The order is what keeps neighbouring series apart for colour-blind readers. The set was checked as a whole in each theme, against the surface it is drawn on, for lightness, chroma, separation under simulated protanopia and deuteranopia, and separation for full-colour vision. Do not add or reorder a colour by eye. In the light theme three of the eight sit under 3 to 1 against white, which the table view is there to make up for. A test holds every chart colour to a floor against the surface in both themes. + +## How a turn is shown + +A turn is shown as its answer. What the assistant did on the way is one list of steps above it, open while the turn runs and folded away when it ends. + +- A step is a call the assistant made, with its SQL and its result, or what the assistant wrote before going on to another call. +- A call that failed is not listed. A model reads the error, corrects the statement and runs it again. Those attempts are written to the app's log, with the statement and what came back. +- A call the operator was asked to approve stays in the list whatever became of it, because the decision was theirs. If they approved it and it then failed, the step says why. +- The last statement of the turn that returned rows is shown under the steps as a table that sorts and downloads. So are the statements the assistant asked for together with it, in the same step, up to four in all: a question that takes two statements is shown with both, and what was looked up on the way to them stays in the steps. An answer that holds chart blocks is shown with those instead, each with its own table. +- What the turn used is said on the line that heads the steps, once the turn has ended: `6 steps 25,469 tokens in (12,631 cached), 158 out`. A turn with no steps says it on a line of its own in the same place. It is small and to the side, since it is not part of the answer. See "Token counts" below. +- The host says which step of the model a call belongs to. Its own loop knows each step. A delegated agent does not say where a step ends, so there the calls that follow one of the agent's messages count as one step. + +Every statement the agent runs is still on record: the engine writes each one to its audit log, which the Activity view lists with its outcome. + +## Token counts + +The counts are the provider's own, passed on. Nothing is estimated: a count a provider does not report is not shown, and a provider that reports none leaves the line out. + +- Tokens in is everything the model was sent in the turn, whether or not the provider read part of it from its cache. The cached part is said in brackets where the provider tells it apart. +- Tokens out is everything the model wrote, with its thinking where the provider counts it. +- Both are added up over every call to the model in the turn. Each call sends the conversation so far again, with the engine's guidance, so a turn of ten calls counts that ten times. That is how it is billed where billing is by the token. + +Where each count comes from is below. + +| Backend | Tokens in | Cached | Tokens out | +|---|---|---|---| +| Gemini | `promptTokenCount` plus `toolUsePromptTokenCount` | `cachedContentTokenCount` | `candidatesTokenCount` plus `thoughtsTokenCount`, which the API counts apart and bills as output | +| Anthropic | `input_tokens` plus the two cache counts, which the API reports apart from it | `cache_read_input_tokens` | `output_tokens` | +| OpenAI-compatible | `prompt_tokens` | `prompt_tokens_details.cached_tokens`, which a local server usually does not send | `completion_tokens` | +| GitHub Copilot CLI | `inputTokens` from the answer to the prompt | `cachedReadTokens` | `outputTokens`. The run observed did not show whether that holds the model's thinking | + +A turn that fails before it ends has no count, because the host learns the count from how the turn ends. On the Copilot CLI the count is not the cost: that plan is billed by the request. What the CLI reports was observed, and is in `docs/spike-acp.md`. + +## The log + +The host writes its own log, one file for each run of the app, in `/logs`. A file is named `stackql_workbench_.log` and holds one JSON object on each line. Help > Show Log File opens the folder with the current file selected. The 20 newest files are kept. + +It is a different record from the engine's audit log in `/audit`, which the engine writes. + +| Event | When | +|---|---| +| `app_started` | The app starts | +| `engine_running`, `engine_failed` | The engine comes up, or does not | +| `tool_call_failed` | A call the assistant made ended as an error, with the tool, the statement or arguments, and what came back | +| `notice` | The host had something to tell the operator during a turn | +| `turn_finished`, `turn_failed` | A turn ends. A turn that finished is written with its token counts, where the provider reported them | + +A record never holds an API key, an environment value or what the operator typed to the assistant. diff --git a/docs/spike-acp.md b/docs/spike-acp.md new file mode 100644 index 0000000..46820d3 --- /dev/null +++ b/docs/spike-acp.md @@ -0,0 +1,161 @@ +# Spike: a delegated agent over ACP + +This note records what was tested before building the delegated chat backend, the one in which an agent the operator already has installed and signed in to runs the model. It was run on Windows 11 x64 against GitHub Copilot CLI 1.0.113 and `stackql` v1.0.888, on 18 November 2026. + +## Why + +The API key backends need a key from an inference provider. An operator who already pays for a coding agent would rather use that. The Agent Client Protocol (ACP) lets one program drive another program's agent over stdio, and the agent keeps its own sign-in. Workbench never sees or handles that credential, which is what the inference rules in `CLAUDE.md` require. + +The questions were whether the agent can be made to use only the Workbench's engine, in the Workbench's safety mode, and whether the engine's approval prompt survives the trip. + +## Method + +The probe is hand-built JSON-RPC over the stdio of `copilot --acp`, so no client library hides anything. The wire shapes were taken from the protocol documentation at agentclientprotocol.com and from `copilot help acp`, `copilot help mcp` and `copilot help permissions`. + +Four prompts were sent in total, all on the cheapest model the account offers. Everything else below was learned from the handshake and from opening sessions, which use no quota. + +## Findings + +Each finding is something that was observed, not read. + +| Question | Finding | +|---|---| +| Framing | One JSON-RPC message per line on stdout and stdin. Logs go to stderr or to `--log-dir` | +| Protocol version | `1` is offered and accepted | +| Sign-in | The CLI uses its own. `initialize` lists one method, `copilot-login`, which is to run `copilot login` in a terminal. There is nothing for the client to do or hold | +| Agent capabilities | `loadSession`, `sessionCapabilities.close` and `list`, `mcpCapabilities.http` and `sse`. No `systemPrompt` capability | +| `session/new` | Returns `sessionId`, `models.availableModels` with a usage multiplier per model, `models.currentModelId`, `modes` and `configOptions` | +| Choosing a model | `session/set_config_option` with `configId: "model"` works | +| MCP servers passed in `session/new` | A stdio server is rejected. The log says `Rejecting non-http/sse MCP server "..." from client`. The request still succeeds, and the session carries on with the servers from the operator's own Copilot configuration | +| MCP servers passed at start | `--additional-mcp-config @file` works, and a server named there replaces one of the same name from the operator's configuration | +| What the model can reach by default | A shell, file reads and writes, web fetch and every MCP server the operator has configured | +| Restricting tools | `--available-tools` with the names `stackql-` leaves the model with those tools only. The CLI reports the rest as disabled | +| Permission prompts | An MCP tool call asks through `session/request_permission` unless a rule allows it. `--allow-tool=stackql` allows the server's tools, and no prompt is sent | +| Tool calls | `tool_call` carries `toolCallId`, `title` (`stackql-run_select_query`), `kind` and `rawInput` with the arguments. Calls can run in parallel | +| Tool results | `tool_call_update` carries `status`, the rendered text, and `rawOutput.structuredContent` with the same `{ "rows": [...] }` payload the host gets when it is the MCP client. A failure carries `rawOutput.message` | +| Text | `agent_message_chunk` streams the reply in small pieces, each with a `messageId`. Lines the CLI itself adds, such as the list of disabled tools, come as chunks with no `messageId` | +| Approval prompts | Not relayed. See below | +| Audit log | The engine writes it as usual, to `server.audit.file.dir`. The activity pane needs no change | + +## The approval prompt does not get through + +In `safe` mode the engine asks for approval with an MCP elicitation, and refuses if the client cannot answer one. The Copilot CLI does not advertise elicitation to MCP servers in ACP mode. That held even when the ACP client advertised `elicitation.form`, the ACP capability for showing such a prompt. + +The engine's answer to a gated statement was: + +``` +tool "run_mutation_query" refused: server is in 'safe' mode and the MCP client +does not support elicitation. Restart the server in 'full_access' mode if you +trust this client, or use an elicitation-capable client +``` + +The audit log recorded the decision as `needs_approval_unavailable`. Nothing was run. + +So the engine fails closed. With this backend a statement that needs approval is refused, not asked about. What the modes come to is below. + +| Mode | With an API key backend | With the Copilot CLI | +|---|---|---| +| `read_only` | Reads only | Reads only | +| `safe` | Changes ask for approval | Changes are refused | +| `delete_safe` | Inserts and updates run, deletes and `EXEC` ask | Inserts and updates run, deletes and `EXEC` are refused | +| `full_access` | Everything runs | Everything runs | + +The host does not put a gate of its own in the way. The CLI's permission prompt could be shown as an approval card, but it works on tool names, not on what a statement does, and it would only matter with the engine in `full_access`. That would move the decision out of the engine, which `CLAUDE.md` rules out. + +## What the host does + +These follow from the findings. + +- Starts `copilot --acp` itself, under the supervisor, with the engine's MCP server named in `--additional-mcp-config`. The server is called `stackql`, so it replaces an entry of that name in the operator's own configuration instead of running beside it. +- Passes `--available-tools` with the engine's tool names, read from the engine, so the model has no shell, no file access and no other MCP server. +- Passes `--allow-tool=stackql`, `--disable-builtin-mcps`, `--no-custom-instructions` and `--no-ask-user`. +- Passes the workspace safety mode to the engine as it does for the other backends. The mode is fixed when the CLI starts, so changing it starts a new CLI session. +- Declines any `session/request_permission`. With the flags above none is expected, and one would mean the agent is reaching for something outside the engine. +- Uses an empty folder under the app data directory as the session's working directory. + +## Subagents + +This was tested on 18 November 2026, on the same versions, to see whether the CLI's subagents can be allowed without giving up the restriction to the engine. Three prompts were sent to the probe and two through the app. + +The short version: allowing them is safe, and it is not yet dependable. They are off unless the operator turns them on. + +The CLI has a `task` tool that starts a subagent. It is one of the tools the restriction above turns off. Adding `task` to `--available-tools` brings it back and nothing else. + +| Question | Finding | +|---|---| +| What a subagent can use | The engine's tools and `task`. Asked to run a shell command and to create a file, a subagent had no tool for either. No permission was requested and nothing was written | +| Which engine a subagent talks to | The same MCP server process as the main agent. One audit file was opened for the session, and `server_info` called from a subagent reported the mode the server was started in | +| How a start is reported | A `tool_call` whose `rawInput` has `agent_type: "task"`, with `name`, `description` and `prompt`. Its result, when the subagent is done, is the subagent's report | +| How a subagent's work is reported | Its tool calls and message chunks are ordinary `session/update` messages that carry `_meta["github.com/copilot"].agentId`. The main agent's carry no `_meta` | +| Naming a subagent | Asking for `subagent.started` at the handshake, under `clientCapabilities._meta["github.com/copilot"].events`, gives a `github.com/copilot/sessionEvent` notification with the `agentId`, a display name, the call that started it and the model | +| Kinds of subagent | Three: `general-purpose`, `task` and `explore`. The model picks one with `agent_type`. See the table below | +| Running together | Two subagents started in one step ran at the same time | +| Nesting | A subagent can start subagents. One that could not do its job did so, and the CLI stopped it at depth four with `Maximum sub-agent depth of 4 reached` | + +The three kinds were each asked to run a shell command, to create a file, and to call an engine tool. + +| Kind | Shell | File write | Engine tools | Model | +|---|---|---|---|---| +| `general-purpose` | No | No | Yes | The session's model | +| `task` | No | No | Yes | `gpt-6-luna`, the agent definition's default | +| `explore` | No | No | No | `gpt-6-luna` | + +So the restriction holds for every kind, and only two of them are of use here. This matters in practice. Left to choose, the model once picked `explore` in background mode. Those subagents could not reach the engine, their results had to be read back with a tool the agent does not have under this tool list, and the main agent ended up doing the lookups itself. The answer was right and the subagents were wasted. + +A subagent that lacks a tool for its job tends to start a `task` subagent to try again, even when told not to. That is what the depth limit catches. + +After the agent was told which kind to use, the same question was asked again without naming subagents. The model did the two lookups itself, at the same time, and got a large result. The CLI keeps a large tool result in a temporary file and tells the model to read it, and the model has no tool that reads files here. It then started a subagent to count the result. That subagent could not read the file either and started another, four deep, twice. Ten subagents ran, the turn took 108 seconds, and the count it gave was wrong. Earlier, the same question had been answered correctly in 27 seconds. + +So what the model reached for subagents to do was not the dividing of independent work. It was a way out when it was stuck, and with the `task` tool to hand a stuck model costs more than without it. That was one small model, `claude-haiku-4.5`. A larger one was not tried. + +What the host does with this: + +- Leaves subagents off unless the operator turns them on in settings, where the setting is marked experimental. +- Adds `task` to the tool list when they are on. +- Tells the agent in the first prompt when to use them: for independent lookups only, never for a change, no more than four at once, and not from inside a subagent. +- Tells it how: `agent_type` `general-purpose`, `mode` `sync`, started in one step so they run together, and not the `explore` kind or background mode. +- Shows the start of a subagent with its task, and marks each tool call with the subagent that made it. +- Leaves a subagent's own message text out of the conversation. It arrives whole as the result of the call that started the subagent. +- Stops a turn in which a subagent starts a subagent of its own, at the first one, and says why. In every run where that happened the subagent had been unable to do its job. +- Stops a turn that starts more than 12 subagents, and says why. + +## Token counts + +This was tested on 19 November 2026 against GitHub Copilot CLI 1.0.114, to see whether the agent says what a turn used. One prompt was sent to the probe, on the cheapest model, and one through the app. The prompt to the probe made the model call one engine tool, so the turn took two calls to the model. + +| Question | Finding | +|---|---| +| Does the answer to `session/prompt` carry a count | Yes. Beside `stopReason` it has `usage`, with `inputTokens`, `outputTokens`, `totalTokens`, `thoughtTokens`, `cachedReadTokens` and `cachedWriteTokens` | +| What the count covers | The whole turn, not one call to the model. The run observed gave `inputTokens` 19353 for two calls, while the context window held a little over 9,000 tokens at each | +| Whether the input count holds cached tokens | It did. 19353 was the 9533 read from the cache, the 9805 written to it, and 15 more | +| Whether thinking is in the total | `totalTokens` was `inputTokens` plus `outputTokens`. `thoughtTokens` was 46 and was not added on top, so it is either part of the output count or left out of the total | +| Anything while the turn runs | A `usage_update` after each call to the model, with `used` and `size`: how much of the model's context window the session takes up, 9,343 of 128,000 after the second call. It is not a count of what the turn used | + +What the host does with this: + +- Reads `inputTokens`, `outputTokens` and `cachedReadTokens` from the answer to the prompt, as the turn's use. The input count is taken as the whole input, cached or not, which is what the other backends report too. +- Does not add `thoughtTokens` to anything, since the run did not show whether the output count already holds it. +- Ignores `usage_update`. How full the context window is would be worth showing one day. It is a different number from what a turn used. + +Whether the tokens of a subagent are in the turn's count was not tested. + +On this backend the count is not what the operator pays. The plan is billed by the request, with a multiplier for the model, and the settings pane shows that multiplier. The count still says how large a turn was. + +## Limits + +These are known and accepted for now. + +- No approval card with this backend. See above. +- The engine's stderr goes to the CLI, not to the host, so the operator is not shown what a provider said when a lookup found nothing. A call that fails is not affected: the engine returns it as a tool error, which the CLI passes on. +- The CLI keeps its own session history, so Workbench conversations appear there. +- A different ACP agent needs its own launcher. How the engine's MCP server is handed over, and how tools are restricted, is specific to each agent. +- What subagents cost was not measured. `--usage-output-file` cannot be combined with `--acp`. The CLI's help says subagents count on usage-based billing, and that on request-based billing a prompt costs one request. +- The model a subagent runs on cannot be set over ACP. Asking for the `general-purpose` kind gets the session's model. The agent can still choose another kind. +- ACP support in the Copilot CLI is in public preview. + +## Open questions + +These need an answer from outside this repository. + +- Whether the Copilot CLI will relay MCP elicitation to an ACP client that advertises `elicitation.form`. If it does, the approval card works with no change to the engine. +- Whether the CLI will accept stdio MCP servers in `session/new`, as the protocol describes. That would remove the config file. diff --git a/docs/spike-mcp.md b/docs/spike-mcp.md new file mode 100644 index 0000000..ccff0ca --- /dev/null +++ b/docs/spike-mcp.md @@ -0,0 +1,260 @@ +# MCP spike + +This note records how `stackql mcp` behaves over stdio when driven by the Rust MCP SDK, tested against a real binary. The agent runtime is built on these answers. + +## Setup + +The probe is `src-tauri/examples/mcp_spike.rs`. It starts the MCP server as a child process, keeps ownership of the process, and hands the SDK only the two pipes. That is how the host does it, because one supervisor has to own every child. + +| Item | Value | +|---|---| +| Engine | `stackql v1.0.888 Windows (f7b4116)` | +| Client | `rmcp` 3.11.0, features `client` and `transport-async-rw` | +| Platform | Windows 11 x64 | +| Date | 2026-11-18 | +| Credentials | None. The one approved mutation targets a provider with no credentials and a repository that does not exist | + +To reproduce, run this from `src-tauri`. + +``` +cargo run --example mcp_spike +``` + +## Summary + +Each row is something the agent runtime relies on. + +| Question | Answer | +|---|---| +| Does `rmcp` support the client side of elicitation? | Yes. `ClientHandler::create_elicitation` is called with the server's request and may take as long as it needs to answer | +| Does it support protocol revision negotiation? | Yes. Every revision offered was negotiated, and the negotiated value is readable afterwards | +| Can the host own the process? | Yes. A `(stdout, stdin)` pair is a valid transport, so the supervisor spawns the child and the SDK never does | +| What do tools return? | Rendered text for the model and a structured payload for programs. Row results are `{ "rows": [ { column: value } ] }` | +| How does approval arrive? | As a form elicitation whose message holds the tool, the query class and the exact SQL. The schema has no fields. Accept, decline and cancel all behave as documented | +| What if the client does not advertise elicitation? | Gated tools are refused with a message pointing at `full_access` | +| Provider calls that do not succeed | A call that fails is a tool error with the status and a `retryable` flag. A lookup that finds nothing is "no results" with no error, by design, and what the provider said is on the server's stderr. This row first said failures were hidden from the model. See the correction below | +| Audit log | JSONL, one record per tool call, in the directory given by `server.audit.file.dir` | +| Shutdown | The server exits with code 0 when its stdin closes | + +## Starting the server + +The host starts the server like this. The config is inline JSON. + +``` +stackql mcp --mcp.server.type=stdio --approot --mcp.config '{"server":{"transport":"stdio","mode":"safe","audit":{"format":"jsonl","file":{"dir":""}}}}' +``` + +On stderr the server prints the audit file it opened and a start line. Nothing but protocol frames goes to stdout. + +``` +sink file: \stackql_mcp_server_20261117T230717Z.log +[stackql mcp] 2026-11-17T23:07:17.2019176Z starting: version=1.0.888 platform=Windows pid=26460 transport=stdio ... +``` + +## Protocol revision negotiation + +The client offered four revisions in turn. Each connected and listed all 15 tools. + +``` +offered 2024-11-05: connected in 360 ms, negotiated Some("2024-11-05"), server Some("stackql v0.1.1") +offered 2025-06-18: connected in 84 ms, negotiated Some("2025-06-18"), server Some("stackql v0.1.1") +offered 2025-11-25: connected in 88 ms, negotiated Some("2025-11-25"), server Some("stackql v0.1.1") +offered 2026-07-28: connected in 123 ms, negotiated Some("2025-11-25"), server Some("stackql v0.1.1") +``` + +Notes: + +- `rmcp` offers `2026-07-28` by default, the revision with no `initialize` handshake. Against this server over stdio that settled on `2025-11-25`. +- The host offers `2025-11-25` explicitly (`ProtocolVersion::LATEST_WITH_INITIALIZE`). On that revision the approval prompt is a server-initiated `elicitation/create` request, which is the simpler of the two approval flows. The newer round-trip flow was also exercised and worked through the same handler. +- The server reports its own name and version as `stackql v0.1.1`, which is not the engine version. The engine version comes from the `server_info` tool. +- The handshake returns 25,106 characters of instructions. They are written for the model and the host passes them on as part of the system prompt. +- Connecting takes about 90 ms once the binary is warm. + +## Tools + +The server publishes 15 tools. Every one has a title and all four behaviour hints. + +``` +describe_method args=[format, method, provider, resource, row_limit, service] readOnly=true +list_methods args=[format, method, provider, resource, row_limit, service] readOnly=true +list_providers args=[] readOnly=true +list_registry args=[format, provider, version] readOnly=true openWorld=true +list_resources args=[format, method, provider, resource, row_limit, service] readOnly=true +list_services args=[format, method, provider, resource, row_limit, service] readOnly=true +pull_provider args=[format, provider, version] idempotent=true openWorld=true +query_library_get args=[format, id, params] required=[id] readOnly=true +query_library_search args=[format, include_mutations, intent, limit, provider, service, tags] required=[intent] readOnly=true +reload_credentials args=[format, provider] idempotent=true +run_lifecycle_operation args=[format, row_limit, source, sql] required=[sql] destructive=true openWorld=true +run_mutation_query args=[format, row_limit, source, sql] required=[sql] destructive=true openWorld=true +run_select_query args=[format, row_limit, source, sql] required=[sql] openWorld=true +server_info args=[] readOnly=true +validate_select_query args=[format, row_limit, source, sql] required=[sql] readOnly=true +``` + +The input schemas are plain JSON Schema objects with `additionalProperties: false`. The host passes them to the inference backend unchanged. + +``` +run_select_query input schema: {"additionalProperties":false,"properties":{"format":{"description":"text content render format: markdown (default) or json","type":"string"},"row_limit":{"type":"integer"},"source":{...},"sql":{"type":"string"}},"required":["sql"],"type":"object"} +``` + +The `list_*` schemas mark nothing as required even where the tool needs a provider or a service. The server validates that itself and returns a tool error. + +## Results + +Every result has one text block and, on success, a structured payload. + +``` +> list_providers {} + is_error=None text="| name | version | | |---|---| | | github | v26.08.00448 | ..." + structured={"rows":[{"name":"github","version":"v26.08.00448"},{"name":"homebrew","version":"v25.01.00292"},{"name":"stackql_preview","version":"internal"}]} + +> run_select_query {"sql":"SELECT name, license, versions FROM homebrew.formula.formula WHERE formula_name = 'wget'"} + [307 ms] is_error=None text="| license | name | versions | ..." + structured={"rows":[{"license":"GPL-3.0-or-later","name":"wget","versions":"{\"bottle\":true,\"head\":\"HEAD\",\"stable\":\"1.25.0\"}"}]} + +> server_info {} + structured={"build_date":"2026-11-05T00:26:03Z","commit":"f7b4116","is_read_only":false,"mode":"safe","platform":"Windows","provider_registry":"https://registry.stackql.app/providers","sql_backend":"sqlite3","transport":"stdio","version":"1.0.888"} + +> pull_provider {"provider":"homebrew"} + structured={"messages":["homebrew provider, version 'v25.01.00292' successfully installed"],"timestamp":"..."} +``` + +How the host uses them: + +- The text block goes to the model. It is the form the server renders for that purpose. +- The structured `rows` go to the grid, so agent results appear in the same grid as editor results. Values are text, as on the pg wire channel. +- Row objects come back with their keys in alphabetical order, not in the order of the `SELECT` list. The grid therefore shows agent result columns alphabetically. + +## Failures + +A tool error is a normal result with `is_error` set and the reason in the text. A protocol error is reserved for things like an unknown tool. + +``` +> list_services {"provider":"no_such_provider"} + is_error=Some(true) text="failed to extract query results: no provider document for ..." +> run_select_query {} + is_error=Some(true) text="validating \"arguments\": validating root: required: missing properties: [\"sql\"]" +> no_such_tool {} + protocol error: Mcp error: -32602: unknown tool "no_such_tool" +> run_select_query {"sql":"DELETE FROM github.repos.repos WHERE ..."} + is_error=Some(true) text="tool \"run_select_query\" refused: mutation_delete statements run through run_mutation_query or run_lifecycle_operation" +``` + +A lookup that finds nothing is not an error. The statement below asked a provider API for something that does not exist and got HTTP 404. The model is told there were no results. + +``` +> run_select_query {"sql":"SELECT name FROM homebrew.formula.formula WHERE formula_name = 'no-such-formula-xyz-123'"} + [940 ms] is_error=None text="**no results**" + structured={"rows":[]} + +server stderr: + http response status code: 404, response body: ... +``` + +That is the intended answer. The engine's instructions to a model say that an empty result for something that may or may not exist means "not found", a valid answer. + +### Correction, 18 November 2026 + +This section first concluded that the MCP server hides provider failures from the model, and the host was given a workaround that added a note to the model's tool result. Both were wrong. The conclusion came from the one case above. + +A second case was tested later against the same engine version, with no provider credentials in the environment: + +``` +> run_select_query {"sql":"SELECT login FROM github.users.users"} + is_error=true + text="upstream http error: {\"http_status\": 401, \"retryable\": false}: httpx: request to + https://api.github.com/user failed: status 401: {\"message\":\"Requires authentication\", ...}" + +> run_select_query {"sql":"SELECT name FROM github.repos.repos WHERE org = 'no-such-org-xyz-123-abc'"} + is_error=false text="**no results**" + structured={"rows":[]} + server stderr: http response status code: 404, response body: {"message":"Not Found", ...} +``` + +So a call that fails is a tool error, with the status and whether a retry can help, and only a lookup that finds nothing is an empty result. The engine source says the same: the MCP backend runs statements with strict upstream errors and classifies them. The workaround was removed. The host still shows the stderr line to the operator beside the tool result, and adds nothing to what the model receives. + +## Approval + +In `safe` mode a mutation produces a form elicitation. The message carries the tool, the query class and the exact SQL. The requested schema is an object with no properties, so there is nothing to fill in: the answer is the action alone. + +``` +> run_mutation_query {"sql":"DELETE FROM github.repos.repos WHERE owner = 'nobody-xyz' AND repo = 'nothing-xyz'"} + elicitation request received: + { + "mode": "form", + "message": "Approve run_mutation_query (mutation_delete)?\n\nSQL: DELETE FROM github.repos.repos WHERE owner = 'nobody-xyz' AND repo = 'nothing-xyz'", + "requestedSchema": { "type": "object", "properties": {} } + } +``` + +The three answers: + +| Answer | Tool result | +|---|---| +| decline | `is_error`, `tool "run_mutation_query" refused: user declined approval` | +| cancel | `is_error`, `tool "run_mutation_query" refused: approval prompt was dismissed` | +| accept | The statement runs. Here it failed at the provider: `delete over HTTP error: 404 NOT FOUND` | + +Other cases: + +- A lifecycle operation asks the same way, with `(lifecycle)` as the class. +- A statement the server cannot parse is classed `unknown` and also asks for approval, even through `run_select_query`. `SELEC 1` produced `Approve run_select_query (unknown)?`. The approval card can therefore appear for a read tool. +- A client that does not advertise elicitation is refused: `server is in 'safe' mode and the MCP client does not support elicitation. Restart the server in 'full_access' mode if you trust this client, or use an elicitation-capable client`. +- In `read_only` mode the refusal is immediate: `refused: server is in 'read_only' mode`. + +The host turns each elicitation into an approval card that shows the message and the SQL, and waits for the operator. It never answers on its own. If the operator stops the turn while a card is open, the answer is cancel. + +## Audit log + +The server writes one JSONL record per tool call into the directory from `server.audit.file.dir`. The file name is `stackql_mcp_server_.log`, so there is one file per server start, and servers started in the same second share one. + +``` +{"timestamp":"2026-11-18T10:07:21.4836763+11:00","tool":"list_providers","mode":"safe","decision":"allow","query_class":"select","duration_ms":1} +{"timestamp":"2026-11-18T10:07:21.4865902+11:00","tool":"run_mutation_query","mode":"safe","decision":"needs_approval_declined","query_class":"mutation_delete","sql":"DELETE FROM github.repos.repos WHERE owner = 'nobody-xyz' AND repo = 'nothing-xyz'","args":{"row_limit":0,"sql":"..."},"duration_ms":0,"error":"tool \"run_mutation_query\" refused: user declined approval"} +{"timestamp":"2026-11-18T10:07:21.300807+11:00","tool":"run_mutation_query","mode":"read_only","decision":"refuse_immediate","query_class":"mutation_delete","sql":"...","duration_ms":0,"error":"..."} +{"timestamp":"2026-11-18T10:07:21.205568+11:00","tool":"run_mutation_query","mode":"safe","decision":"needs_approval_unavailable", ...} +``` + +The decisions seen were `allow`, `needs_approval_declined`, `refuse_immediate` and `needs_approval_unavailable`. The activity pane reads these files. Result rows are never in them. + +## Shutdown + +Closing the client closes the server's stdin, and the server exits cleanly. + +``` +client closed: Ok(Cancelled) +server process after its stdin closed: Ok(Ok(ExitStatus(ExitStatus(0)))) +``` + +The supervisor still kills the process if it is alive after that, and the job object or watchdog covers a force quit. + +## Tool calls at the same time + +This was measured on 18 November 2026, after the rest of this report, to see whether independent statements can usefully be sent together. One `stackql mcp` server, v1.0.888, default flags, no provider credentials. Each statement makes one provider request: `SELECT login FROM github.orgs.orgs WHERE org = '...'`, with a different name each time so nothing could be answered from a cache. + +| Run | Four statements, one after another | Four statements, sent together | +|---|---|---| +| 1 | 1344 ms | 2760 ms, with three answers by 339 ms and one late | +| 2 | 1315 ms | 376 ms | +| 3 | 1462 ms | 398 ms | + +So one server does run tool calls at the same time: four together took about as long as one. The late answer in the first run was not explained. This is three runs of small statements, not a load test, and statements that fan out to many provider requests were not tried. + +The host's loop uses this. The tool calls of one model reply run at the same time when the engine marks the tool as not destructive. The engine publishes that on every tool, as `destructiveHint`: + +``` +run_select_query {"destructiveHint":false,"readOnlyHint":false, ...} +list_providers {"destructiveHint":false,"readOnlyHint":true, ...} +pull_provider {"destructiveHint":false,"readOnlyHint":false,"idempotentHint":true, ...} +run_mutation_query {"destructiveHint":true,"readOnlyHint":false, ...} +run_lifecycle_operation {"destructiveHint":true,"readOnlyHint":false, ...} +``` + +A tool marked destructive, or one with no hint, runs alone and in the model's order. The SQL tools are not marked read-only on purpose: the engine's source says they make no such claim because their effect depends on the statement, and that the gate refuses write-class statements on the query tool. + +## Open items for the maintainer + +- Nothing is open on provider errors. The first version of this report asked for an error result from the server, which it already gives. See the correction above. +- Row objects lose the column order of the statement. +- The `list_*` tool schemas do not mark their required arguments. diff --git a/docs/spike-pgwire.md b/docs/spike-pgwire.md new file mode 100644 index 0000000..264e050 --- /dev/null +++ b/docs/spike-pgwire.md @@ -0,0 +1,467 @@ +# pg wire spike + +This note records how `stackql srv` behaves on the Postgres wire protocol, tested against a real binary. Later milestones build on these answers, so each one comes with the evidence it rests on. + +## Setup + +The probe is `src-tauri/examples/pgwire_spike.rs`. It starts the engine itself on a free loopback port with a scratch `--approot`, then talks to it two ways: with hand-built protocol frames, so no client library hides anything, and through `tokio-postgres` 0.7.18, the client the host uses. + +| Item | Value | +|---|---| +| Engine | `stackql v1.0.888 Windows (f7b4116)`, build date 2026-11-05 | +| Platform | Windows 11 x64 | +| Client | `tokio-postgres` 0.7.18 with `NoTls` | +| Date | 2026-11-18 | +| Credentials | None. Statements use provider metadata and two providers that serve public data without authentication (`homebrew`, `github`) | + +To reproduce, run this from `src-tauri`. `--only
` runs one section. + +``` +cargo run --example pgwire_spike +``` + +Nothing here has been run on macOS. The wire behaviour is engine code and is expected to match, but the readiness timings are from Windows only. + +## Summary + +Each row is an answer to one of the spike questions. The sections below hold the evidence. + +| Question | Answer | +|---|---| +| Does `tokio-postgres` connect cleanly? | Yes, with `NoTls`. No password, no TLS, any user and database name accepted | +| Startup, auth, TLS | `AuthenticationOk` straight away, six `ParameterStatus` messages, **no `BackendKeyData`**. An `SSLRequest` is answered `N` | +| Query protocols | Simple protocol only. The extended protocol is not usable through `tokio-postgres` | +| Several statements in one message | **Only the first statement runs. The rest are dropped without an error.** The cut is at the first semicolon, even inside a string literal | +| Identifier quoting | Double quotes, accepted in every metadata statement. Backticks are rejected | +| Column type information | Every column is type OID 25 (`text`) in text format. The one exception seen is `count(*)`, which is OID 1700 (`numeric`). `typlen` is 1024 for everything | +| Are values text? | Yes, always. Booleans arrive as `true`/`false`, numbers as digits, objects and arrays as JSON text | +| NULL | `SELECT NULL` arrives as an empty string, not as a protocol NULL | +| Row count | The command tag is `OK`, with no count. The client must count rows | +| Do rows stream? | No. All rows arrive together when the statement finishes | +| Concurrent connections | Work. Results are correct per connection. Provider calls are serialised across connections, metadata statements are not blocked | +| Are sessions independent? | Errors and notices are per connection. Tables are shared across connections | +| Cancel | **Not supported.** A cancel request has no effect, and closing the connection does not stop the work either | +| Errors | `ErrorResponse` with severity `ERROR`, code `XXUUU` every time, and a message. No position, detail or hint. The connection stays usable | +| Upstream provider failures | By default: an empty, successful result, and the reason only on the engine's stderr. With `--pgsrv.debug.enable`: the reason arrives as a pg notice instead | +| Readiness | 80 to 135 ms from spawn. A successful connect followed by `SHOW VERSION` is a reliable check. Each connect attempt needs its own short timeout | + +## Startup, auth and TLS + +The server asks for nothing. It replies `AuthenticationOk` to any startup message, including one with no parameters at all, and reports itself as server version `150000`. + +``` +SSLRequest reply: 'N' (S = TLS, N = no TLS) +startup params [("user", "stackql"), ("database", "stackql")]: + Authentication code=0 (0 = AuthenticationOk) + ParameterStatus server_encoding=UTF8 + ParameterStatus client_encoding=UTF8 + ParameterStatus standard_conforming_strings=on + ParameterStatus is_superuser=off + ParameterStatus session_authorization=stackql + ParameterStatus server_version=150000 + ReadyForQuery status=I +startup params [("user", "anyone")]: + ... identical, session_authorization=anyone +startup params [("user", "stackql"), ("database", "nonexistent_db"), ("application_name", "spike"), ("client_encoding", "UTF8")]: + ... identical +startup params []: + ... identical, session_authorization= +tokio-postgres connect (user only, NoTls): ok, server_version=Some("150000"), client_encoding=Some("UTF8") +``` + +Three things follow from this. + +- There is no authentication on the listener unless mTLS is configured with `--pgsrv.tls`. Binding to `127.0.0.1` is the only protection, so the host must always pass `--pgsrv.address 127.0.0.1`. Any local process can connect. The open question about a per-launch client certificate stays open. +- `tokio-postgres` with `NoTls` sends no `SSLRequest` under either `SslMode::Disable` or `SslMode::Prefer`. That was read from its `connect_tls.rs`. The host sets `SslMode::Disable` to make the intent explicit. +- The server never sends `BackendKeyData`. `tokio-postgres` therefore holds process id 0 and secret key 0, and a cancel request cannot name a session. See the cancel section. + +## Query protocols + +The simple protocol works. `tokio-postgres` returns a `RowDescription`, the rows as text and a `CommandComplete`. + +``` +-- simple protocol through tokio-postgres + RowDescription ["name", "version"] + Row [Some("github"), Some("v26.08.00448")] + Row [Some("homebrew"), Some("v25.01.00292")] + Row [Some("stackql_preview"), Some("internal")] + CommandComplete 0 +``` + +`CommandComplete 0` is `tokio-postgres` parsing the tag `OK`, which carries no row count. The host counts rows itself. + +The extended protocol does not work through `tokio-postgres`. `Parse` and `Describe` are accepted, but `Describe` reports no parameters and no columns, even for a statement containing `$1`. The server then sends the `RowDescription` during `Execute`, which PostgreSQL never does, and `tokio-postgres` rejects it. + +``` +-- extended protocol: prepare (Parse, Describe, Sync) + prepare ok: SHOW PROVIDERS -> params [], columns [] + prepare ok: SELECT name FROM homebrew.formula.formula WHERE formula_name = $1 -> params [], columns [] +-- extended protocol: query without parameters + query failed: non-db error: unexpected message from server (closed=false) +-- extended protocol: query with a text parameter + query failed: non-db error: expected 0 parameters but got 1 (closed=false) +-- extended protocol: query_typed (no separate prepare round trip) + query_typed failed: non-db error: unexpected message from server (closed=false) + +> Parse/Describe/Bind/Describe/Execute/Sync SHOW PROVIDERS (raw frames) + RowDescription messages 1, rows 3, tags ["OK"], ready Some('I') + other ["ParseComplete", "ParameterDescription []", "NoData", "BindComplete", "NoData"] +``` + +The raw frames show the server does implement the extended flow in its own way, which is why other drivers can use it. It is not usable from this client. The host uses the simple protocol only, so statements are never parameterised. Explorer statements are built in the host from validated identifiers, not from interpolated UI input. + +### Several statements in one message + +This is the finding most likely to surprise. When a simple query message holds more than one statement, the server runs the first and silently drops the rest. A syntax error in a later statement is not reported. + +``` +> SHOW VERSION; SHOW PROVIDERS; + RowDescription messages 1, rows 1, tags ["OK"], ready Some('I') + column version + row ["1.0.888"] + +> SHOW VERSION; SELEC 1; SHOW PROVIDERS; + RowDescription messages 1, rows 1, tags ["OK"], ready Some('I') + row ["1.0.888"] +``` + +The host must split editor text into statements and send them one at a time. `stackql exec` does run every statement in its input, so this is specific to `srv`. + +The cut is made at the first semicolon in the message, with no regard for quoting. A semicolon inside a string literal ends the statement there, and what is left fails to parse. `stackql exec` handles the same text correctly. + +``` +> SELECT 1 AS one, 'a;b' AS s (sent through srv) + ERROR query returns error: ... syntax error at position 20 near 'a' + +> stackql exec "SELECT 1 AS one, 'a;b' AS s" + [{"one":"1","s":"a;b"}] +``` + +The host's splitter respects string literals, quoted identifiers and comments, so it never cuts a statement in the wrong place. It cannot rescue a literal that contains a semicolon, because the engine cuts it again. Such a statement fails with a syntax error until the engine is fixed. + +Other edge cases, for completeness: an empty string and a lone `;` both get `EmptyQueryResponse`. A message holding only a comment gets a `RowDescription` with no columns and the tag `OK`. A trailing `;` or a trailing `--` comment is fine. + +## Column types and values + +Every column of every metadata statement and every provider `SELECT` came back as type OID 25 with format code 0, which is text. `typlen` is 1024 and `table_oid` and `attnum` are 0, none of which match PostgreSQL. The host must not interpret them. + +``` +> SELECT 1 AS one, 'x' AS s, 1.5 AS f, NULL AS n, 1 = 1 AS b + column one type_oid=25 typlen=1024 typmod=-1 format=0 table_oid=0 attnum=0 + column s type_oid=25 ... + column f type_oid=25 ... + column n type_oid=25 ... + column b type_oid=25 ... + row ["1", "x", "1.5", "", "1"] + +> SELECT name, deprecated, versions, aliases, revision, tap FROM homebrew.formula.formula WHERE formula_name = 'wget' + row ["wget", "false", "{\"bottle\":true,\"head\":\"HEAD\",\"stable\":\"1.25.0\"}", "[]", "2", "homebrew/core"] + +> SELECT count(*) AS n FROM github.repos.repos WHERE org = 'stackql' + column n type_oid=1700 typlen=1024 typmod=-1 format=0 + row ["68"] +``` + +Consequences for the grid: + +- Treat every value as text. Type OIDs say nothing useful, so the grid detects JSON by looking at the value: a cell that starts with `{` or `[` and parses is offered in the cell viewer. +- `NULL` and the empty string cannot be told apart. `SELECT NULL` produced a zero-length value, not the protocol NULL marker. The host still maps a protocol NULL to `null` in case the engine sends one, but the grid cannot promise to show NULLs. +- A statement with no matching rows still returns its `RowDescription`, so the grid can show headers for an empty result. + +## Rows do not stream + +Rows are buffered in the engine and sent together at the end. The probe used `simple_query_raw`, which yields messages as they arrive, on a statement that makes twelve provider calls in sequence. + +``` +-- simple_query_raw: do rows arrive incrementally? + 2774 ms RowDescription + 2774 ms Row Some("wget") + 2774 ms Row Some("curl") + ... + 2774 ms Row Some("xz") + 2774 ms CommandComplete 0 +``` + +Everything, including the `RowDescription`, arrived at 2774 ms. The host still forwards rows to the webview in batches, because a large result should not cross IPC as one message, but the operator sees nothing until the statement completes. A progress indicator is honest. A partial grid is not possible. + +## Concurrent connections and sessions + +Several connections work at once and each gets its own correct result. + +``` +backend key data per connection: [(None, None), (None, None), (None, None), (None, None)] +one connection, 8 upstream calls: 191 ms, rows 8 +four connections at once, wall time 1841 ms + conn 0: 109 ms, rows 8, correct rows true, errors 0 + conn 1: 956 ms, rows 8, correct rows true, errors 0 + conn 2: 1810 ms, rows 8, correct rows true, errors 0 + conn 3: 1840 ms, rows 8, correct rows true, errors 0 +metadata statement issued 300 ms into a 2067 ms statement on another connection: finished at 305 ms (took 2 ms) +``` + +The four statements finished one after another, not together, which fits the engine's default `--execution.concurrency.limit 1`: provider calls queue across connections. The timings are also affected by the upstream API serving repeat requests faster, so treat the numbers as indicative. A metadata statement on a second connection was not held up by a slow statement on the first. That is what the explorer needs. + +Session independence is partial. + +``` +error on A (errors 1), then B still fine: true +> [A] SET SESSION "$.auth.github.type" = 'null_auth' tags ["OK"] +> [A] SHOW TRANSACTION ISOLATION LEVEL row ["read committed"] +> [A] BEGIN tags ["OK"] +> [A] COMMIT tags ["OK"] +> [A] CREATE TABLE spike_t (id int) tags ["OK"] +> [A] SELECT * FROM spike_t column id, rows 0 +> [B] SELECT * FROM spike_t column id, rows 0 +B after A closed: rows 1, errors 0 +``` + +- An error on one connection does not disturb another, and closing one leaves the other working. +- A table created on connection A is visible on connection B. The SQL backend is shared by the whole engine process. +- `SET SESSION` is accepted. Whether its effect is limited to the connection was not tested, because observing it needs provider credentials. The notice buffer is per connection, see below, so some per-connection state exists. + +The host keeps one long-lived connection for the editor, so that whatever session state the engine holds behaves as it would in `psql`, and opens a short-lived connection for each explorer statement. A handshake costs about 3 ms. + +## Cancel + +Cancel does not work, in any form. + +The server sends no `BackendKeyData`, so there is no process id or secret key to put in a `CancelRequest`. `tokio-postgres` sends one anyway with zeros. To see what actually happens, the engine was started with `--http.log.enabled`, which logs each provider call, and a statement making 60 provider calls was interrupted 250 ms in. + +``` +-- baseline: 60 upstream calls, not cancelled + BackendKeyData in handshake: false + elapsed 12145 ms, rows 60, errors 0 +-- tokio-postgres cancel_token().cancel_query sent 250 ms in + cancel_query result: Ok(()) + statement completed normally in 1011 ms with 62 messages + upstream requests logged before the cancel: 0, after: 60 +-- closing the client socket 250 ms into the statement + upstream requests logged before the close: 0, after: 60 + engine still serving new connections: true +-- dropping the tokio-postgres client 250 ms into the statement + upstream requests logged before the drop: 0, after: 60 +``` + +After the cancel request the statement ran to completion and returned every row. After the client closed its socket, the engine still made all 60 provider calls. The baseline is slower than the later runs only because the upstream API answers repeat requests faster. + +Consequences: + +- The host does not offer "cancel". It offers "stop waiting", which abandons the result and reconnects the editor session. The UI says plainly that the statement keeps running in the engine and that a mutation may still complete. +- The only way to actually stop a statement is to restart the engine, which the status bar offers. +- M1 lists cancel as a feature. It needs engine support first: `BackendKeyData` at startup and a handler for `CancelRequest`. This is a question for the maintainer. + +## Errors + +Every error is an `ErrorResponse` with three fields: severity `ERROR`, the code `XXUUU`, and a message that starts with `query returns error: `. There is no position, detail or hint, and the code does not vary with the kind of error. The connection is ready for the next statement afterwards. + +``` +> SELEC 1 + ERROR {'C': "XXUUU", 'M': "query returns error: error: You have an error in your stackql syntax; parser error: Code: INVALID_ARGUMENT syntax error at position 6 near 'SELEC' ", 'S': "ERROR"} +> SHOW SERVICES IN nosuchprovider + ERROR {'C': "XXUUU", 'M': "query returns error: no provider document for 'stackql_unstable_nosuchprovider' under '\\src\\nosuchprovider'", 'S': "ERROR"} +> SELECT name FROM homebrew.formula.formula + ERROR {'C': "XXUUU", 'M': "query returns error: omnisdk: formula (stackql_unstable_homebrew.formula.formula): no satisfiable select method (get_formula needs formula_name)", 'S': "ERROR"} +> SELECT nosuchcolumn FROM homebrew.formula.formula WHERE formula_name = 'wget' + ERROR {'C': "XXUUU", 'M': "query returns error: omnisdk: output \"nosuchcolumn\": no such column: nosuchcolumn (no table has a column \"nosuchcolumn\")", 'S': "ERROR"} +> REGISTRY PULL nosuchprovider + ERROR {'C': "XXUUU", 'M': "query returns error: could not resolve provider 'nosuchprovider'", 'S': "ERROR"} + +connection still usable after the errors: true +-- the same errors through tokio-postgres + SELEC 1: DbError severity=ERROR code=XXUUU message="query returns error: ..." detail=None hint=None position=None where=None routine=None + client.is_closed after errors: false +``` + +The host carries severity, code and message across IPC and strips nothing. A syntax error position is sometimes present inside the message text ("at position 6"), but it is not a protocol field, so the editor cannot mark the location reliably. + +## Upstream provider failures + +This is the behaviour [CLAUDE.md](../CLAUDE.md) warned about, now pinned down. When a provider API call fails, the statement **succeeds with zero rows**. Nothing on the wire says anything went wrong. + +With default flags the reason goes only to the engine's stderr. + +``` +-- server started with default flags +> SELECT login FROM github.users.users + RowDescription messages 1, rows 0, tags ["OK"], ready Some('I') + column login + srv [ 1.298s stderr] http response status code: 401, response body: {"message":"Requires authentication", ... ,"status":"401"} + notices via tokio-postgres poll_message: [] +``` + +With `--pgsrv.debug.enable` the same text arrives as a `NoticeResponse` on the connection that ran the statement, and stderr stays silent. The notice has severity `NOTICE`, code `01000`, the fixed message `a notice level event has occurred`, and the useful text in the detail field. + +``` +-- server started with --pgsrv.debug.enable +> SELECT name FROM homebrew.formula.formula WHERE formula_name = 'no-such-formula-xyz-123' + RowDescription messages 1, rows 0, tags [""], ready Some('I') + NOTICE {'C': "01000", 'D': "http response status code: 404, response body: ...", 'M': "a notice level event has occurred", 'S': "NOTICE", 'V': "NOTICE"} +``` + +`--pgsrv.loglevel DEBUG` changed nothing visible. `--http.log.enabled` logs every request and the full response body to stderr, which is far too much to leave on. + +A partial failure looks like a smaller result. One good branch and one failing branch of a `UNION ALL` returned the good row and no error. + +### Notices accumulate on a connection + +The notice buffer is per connection and is never cleared. Once a statement has produced a notice, every later statement on that connection gets the whole accumulated text again, including statements that succeed. + +``` +== notices under --pgsrv.debug.enable == + A SHOW PROVIDERS: rows 3, tags ["OK"], notices 0 + A good select: rows 1, tags ["OK"], notices 0 + A failing select 1: rows 0, tags [""], notices 1 [detail 9427 chars, 'status code' occurrences 1] + A SHOW PROVIDERS: rows 3, tags [""], notices 1 [detail 9427 chars, 'status code' occurrences 1] + A good select: rows 1, tags [""], notices 1 [detail 9427 chars, 'status code' occurrences 1] + A failing select 2: rows 0, tags [""], notices 1 [detail 9607 chars, 'status code' occurrences 2] + A syntax error: rows 0, tags [], errors 1, notices 0 + A REGISTRY LIST: rows 44, tags [""], notices 1 [detail 9607 chars, 'status code' occurrences 2] + B failing select 2 (fresh connection): notices 1 [detail 180 chars, 'status code' occurrences 1] + C good select (new connection after failures elsewhere): rows 1, tags ["OK"], notices 0 + engine stderr/stdout lines captured with the flag on: 0 +``` + +Consequences: + +- The host starts `srv` with `--pgsrv.debug.enable`. A notice tied to the connection is far better attribution than a stderr line with no statement attached. +- On the long-lived editor connection the host remembers the notice text it has already shown and reports only what was appended. A repeat of the same text is treated as old news. +- Stderr is still captured and shown, since the engine may write other things there. +- A zero-row result with a notice is the signature of an upstream failure. The results pane shows the notice prominently in that case, so an empty grid is not mistaken for "no data". +- The command tag changes from `OK` to an empty string once a notice exists. The host does not rely on the tag. + +## Metadata statements + +These are the exact column names and order the explorer relies on, read from `RowDescription`. Every column is text. + +| Statement | Columns, in order | +|---|---| +| `SHOW VERSION` | `version` | +| `SHOW EXTENDED VERSION` | `version`, `commit`, `build_date`, `platform` | +| `SHOW PROVIDERS` | `name`, `version` | +| `SHOW EXTENDED PROVIDERS` | `name`, `version` | +| `REGISTRY LIST` | `provider`, `version` | +| `REGISTRY PULL ` | No result set. Tag `OK` | +| `SHOW SERVICES IN ` | `id`, `name`, `title` | +| `SHOW EXTENDED SERVICES IN ` | `id`, `name`, `title`, `description`, `version`, `preferred` | +| `SHOW RESOURCES IN .` | `name`, `id` | +| `SHOW EXTENDED RESOURCES IN .` | `name`, `id`, `description` | +| `SHOW METHODS IN ..` | `MethodName`, `RequiredParams`, `SQLVerb` | +| `SHOW EXTENDED METHODS IN ..` | `MethodName`, `RequiredParams`, `SQLVerb`, `description` | +| `DESCRIBE ..` | `name`, `type` | +| `DESCRIBE EXTENDED ..` | `name`, `type`, `description` | +| `DESCRIBE METHOD ...` | `name`, `type`, `param_type`, `shape` | +| `DESCRIBE METHOD EXTENDED <...>` | `name`, `type`, `param_type`, `shape`, `description` | + +Sample rows, to show the shapes: + +``` +> SHOW PROVIDERS + row ["github", "v26.08.00448"] + row ["homebrew", "v25.01.00292"] + row ["stackql_preview", "internal"] + +> SHOW SERVICES IN homebrew + row ["formula:v25.01.00292", "formula", "Homebrew Formulae API"] + +> SHOW RESOURCES IN homebrew.formula + row ["formula", "homebrew.formula.formula"] + row ["vw_build_errors", "homebrew.formula.vw_build_errors"] + +> SHOW EXTENDED METHODS IN github.repos.repos + row ["list_for_org", "org", "SELECT", "repos/list-for-org"] + row ["list_for_user", "username", "SELECT", "repos/list-for-user"] + row ["list_public", "", "SELECT", "repos/list-public"] + +> DESCRIBE homebrew.formula.formula + row ["name", "string"] + row ["aliases", "array"] + row ["analytics", "object"] + +> DESCRIBE METHOD homebrew.formula.formula.get_formula + row ["formula_name", "string", "input_required", "string"] + row ["aliases", "array", "output", "array"] +``` + +Notes for the explorer: + +- The service `id` is `:`, not a path. Use `name` to build the next level. +- The resource `id` is the fully qualified name, `..`. +- A fresh approot lists one provider, `stackql_preview` with version `internal`. Others appear after `REGISTRY PULL`. +- `RequiredParams` is a comma-separated string and may be empty. +- `param_type` is `input_required`, `input_optional` or `output`. The `output` rows are the columns a `SELECT` through that method can return. +- Views show up as resources (`vw_*`). `DESCRIBE` on a view can return an empty `type`. +- The keyword order is `DESCRIBE METHOD EXTENDED`. `DESCRIBE EXTENDED METHOD` is a syntax error. +- Identifiers are quoted with double quotes. Every statement in the table above accepts double-quoted names, for example `SHOW EXTENDED RESOURCES IN "homebrew"."formula"`, so the host quotes every name it puts in a statement. Backticks are rejected everywhere in this engine version, although the public documentation suggests them for names that contain dots. +- A column name that is a reserved word, such as `desc`, must be written in double quotes. +- `SHOW EXTENDED METHODS` on a large provider took 251 ms the first time, while the provider document loaded. Everything else took single-digit milliseconds. + +Notes on the registry and on generated statements, tested on 18 November 2026 against v1.0.888 with `stackql exec` and a data folder of its own: + +- `REGISTRY LIST` gives one row for each provider, 44 of them, with the newest version only. `REGISTRY LIST ` gives one row with every version in a `versions` column. +- Every provider name in the registry is a plain identifier. +- With an older version installed, `SHOW PROVIDERS` reports that older version, so comparing it with `REGISTRY LIST` shows that an update exists. Versions have the form `v26.08.00448` and compare by their three numbers. +- `REGISTRY PULL ` with no version installs the newest one and replaces the older one. The data folder then holds only the newer version. `REGISTRY PULL "github"` with the name in double quotes works too. +- A double-quoted name in a select list is read as a column, not as a string. `SELECT "name", language FROM github.repos.repos WHERE org = 'stackql'` returned the names. +- A `SELECT` that lists all 90 output fields of `github.repos.repos.list_for_org` ran. None of those names needed quoting. +- Request body fields of the GitHub provider are reported with a `data__` prefix, for example `data__name`. A generated statement uses the reported names as they are, which is what the engine's own guidance asks for. + +Notes on `stackql exec` from a shell, tested the same day. They are behind the "Copy as CLI" command, which is not on the pg wire channel but is recorded here with the other engine findings: + +- `exec` does not read a statement from standard input, although `--infile` says its default is `stdin`. With no statement it prints its usage. `-i -` is read as a file named `-`. +- A statement that starts with a `--` comment is read as a flag and refused with `unknown flag`. Putting `--` before the statement fixes that. A comment further down the statement is fine. +- Several statements in one argument run in order. +- Windows PowerShell 5.1 and PowerShell 7 pass a double quote inside an argument differently. With `"` written as it is, 5.1 drops the quotes and 7.7 keeps them. With `\"`, 5.1 keeps them and 7.7 passes the backslash through, which the engine refuses. No one spelling works in both. +- A statement written to a file from a single-quoted here-string and passed with `-i` works in both, whatever it contains. +- What the app produces was run in Windows PowerShell 5.1.26100 and PowerShell 7.7.0 against the real engine, with a plain statement, a statement of several lines with a leading comment, one with double quotes, and two statements. In a POSIX shell under WSL the arguments were checked with a stand-in program, including a path with a single quote in it. + +## Readiness + +The engine was started five times and polled, with each connect attempt limited to 40 ms. + +``` +run 1: tcp accept 132 ms, handshake ready 134 ms, first SHOW VERSION result 135 ms, attempts 3 +run 2: tcp accept 129 ms, handshake ready 131 ms, first SHOW VERSION result 132 ms, attempts 3 +run 3: tcp accept 130 ms, handshake ready 134 ms, first SHOW VERSION result 135 ms, attempts 3 +run 4: tcp accept 78 ms, handshake ready 81 ms, first SHOW VERSION result 82 ms, attempts 2 +run 5: tcp accept 132 ms, handshake ready 134 ms, first SHOW VERSION result 135 ms, attempts 3 +``` + +The engine is ready roughly 80 to 135 ms after spawn. The spread is the polling interval, not the engine. + +An earlier run without the 40 ms limit reported about 520 ms every time, with the first attempt succeeding. On Windows a connect to a loopback port that is not listening yet is retried inside the OS for about half a second before it fails, so one unbounded attempt hides the real figure. The host must put its own short timeout on each connect attempt. + +``` +run 1: tcp accept 516 ms, handshake ready 519 ms, first SHOW VERSION result 523 ms, attempts 1 (unbounded connect) +``` + +There was no gap between the port accepting connections and statements working: the handshake and `SHOW VERSION` succeeded within 5 ms of the first accepted connection. The engine prints nothing on stdout or stderr at startup, so there is no log line to wait for. + +The readiness check the host uses: connect with a short per-attempt timeout and run `SHOW VERSION`, retrying until it returns one row, with an overall timeout of 15 seconds. `SHOW VERSION` needs no provider, no registry access and no credentials, and its result doubles as the engine version shown in the status bar. If the child exits first, the host reports the captured stderr instead of waiting out the timeout. + +## What this changes + +These are the decisions the findings forced, and where they landed. + +| Finding | Decision | +|---|---| +| Simple protocol only | The host uses `simple_query_raw`. No prepared statements, no parameters | +| Only the first statement in a message runs | The host splits editor text into statements and sends them one at a time, stopping at the first error | +| No row count in the tag | The host counts rows | +| Everything is text | The result type carries column names only. The grid detects JSON from the value | +| No streaming | Rows cross IPC in batches for size reasons, with a busy indicator while waiting | +| No cancel | "Stop waiting" abandons the result and reconnects. The UI says the statement may still complete | +| Upstream failures are silent by default | `srv` is started with `--pgsrv.debug.enable`, and notices are shown beside the result | +| Notices accumulate per connection | The editor connection reports only newly appended notice text | +| Default approot is the working directory | The host passes `--approot` explicitly: a folder of its own beside the executable, or one the operator names | + +## Open items for the maintainer + +These came out of the spike and need an engine-side answer. + +- Cancel needs `BackendKeyData` and a `CancelRequest` handler in `srv`. Without them M1's cancel is a "stop waiting" button only. +- Dropping statements after the first, with no error, looks like a defect in `srv`. The host works around it by splitting. +- `srv` cuts a message at the first semicolon even inside a string literal, so a literal containing a semicolon cannot be sent. There is no host-side workaround. +- The per-connection notice buffer is never cleared. The host works around it, but a fix in the engine would be cleaner. +- A provider call that returns nothing gives success with zero rows, which is easy to misread. This report first suggested an error. The maintainer has since decided the behaviour stays: an empty result is the right answer to a lookup of something that does not exist. The host shows the notice beside the empty result and does not rule on it. See Provider errors and empty results in `CLAUDE.md`. +- `NULL` arrives as an empty string. +- Whether `SET SESSION` is scoped to the connection was not verified. diff --git a/eslint.config.js b/eslint.config.js new file mode 100644 index 0000000..c3b3a53 --- /dev/null +++ b/eslint.config.js @@ -0,0 +1,64 @@ +import js from '@eslint/js'; +import eslintConfigPrettier from 'eslint-config-prettier/flat'; +import reactHooks from 'eslint-plugin-react-hooks'; +import { defineConfig, globalIgnores } from 'eslint/config'; +import tseslint from 'typescript-eslint'; + +export default defineConfig([ + globalIgnores(['dist/', 'src-tauri/', 'node_modules/', 'coverage/']), + { + files: ['**/*.{ts,tsx}'], + extends: [ + js.configs.recommended, + tseslint.configs.strictTypeChecked, + reactHooks.configs.flat.recommended, + ], + languageOptions: { + parserOptions: { + projectService: true, + tsconfigRootDir: import.meta.dirname, + }, + }, + rules: { + '@typescript-eslint/no-explicit-any': 'error', + '@typescript-eslint/consistent-type-imports': 'error', + // Numbers and booleans read fine in template strings. + '@typescript-eslint/restrict-template-expressions': [ + 'error', + { allowNumber: true, allowBoolean: true }, + ], + }, + }, + { + // Architecture rule: only src/host/ may touch Tauri. Panes call the typed + // wrappers in that directory. + files: ['src/**/*.{ts,tsx}'], + ignores: ['src/host/**'], + rules: { + 'no-restricted-imports': [ + 'error', + { + patterns: [ + { + group: ['@tauri-apps/*'], + message: 'Only src/host/ may import Tauri APIs. Use the typed wrappers in src/host/.', + }, + ], + }, + ], + }, + }, + { + // Tests pass mock functions to expect(), which this rule reads as + // detaching a method from its object. + files: ['**/*.test.{ts,tsx}'], + rules: { + '@typescript-eslint/unbound-method': 'off', + }, + }, + { + files: ['**/*.js'], + extends: [js.configs.recommended], + }, + eslintConfigPrettier, +]); diff --git a/index.html b/index.html new file mode 100644 index 0000000..bf2bdef --- /dev/null +++ b/index.html @@ -0,0 +1,12 @@ + + + + + + StackQL Workbench + + +
+ + + diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..5998efd --- /dev/null +++ b/package-lock.json @@ -0,0 +1,4429 @@ +{ + "name": "stackql-workbench", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "stackql-workbench", + "version": "0.1.0", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.20.4", + "@codemirror/commands": "^6.11.1", + "@codemirror/lang-sql": "^6.10.0", + "@codemirror/language": "^6.13.1", + "@codemirror/state": "^6.7.6", + "@codemirror/view": "^6.43.15", + "@lezer/highlight": "^1.2.5", + "@tanstack/react-table": "^9.3.1", + "@tanstack/react-virtual": "^3.14.26", + "@tauri-apps/api": "^2.12.5", + "codemirror": "^6.0.2", + "react": "^19.3.1", + "react-dom": "^19.3.1" + }, + "devDependencies": { + "@eslint/js": "^10.0.1", + "@tailwindcss/vite": "^4.3.5", + "@tauri-apps/cli": "^2.12.5", + "@types/node": "^24.19.2", + "@types/react": "^19.3.0", + "@types/react-dom": "^19.3.0", + "@vitejs/plugin-react": "^6.3.0", + "eslint": "^10.15.0", + "eslint-config-prettier": "^10.1.8", + "eslint-plugin-react-hooks": "^7.1.1", + "jsdom": "^31.0.1", + "prettier": "^3.10.1", + "tailwindcss": "^4.3.5", + "typescript": "~6.0.3", + "typescript-eslint": "^8.73.0", + "vite": "^8.3.8", + "vitest": "^5.1.0" + } + }, + "node_modules/@babel/code-frame": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz", + "integrity": "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-validator-identifier": "^7.29.7", + "js-tokens": "^4.0.0", + "picocolors": "^1.1.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/compat-data": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.7.tgz", + "integrity": "sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/core": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.13.tgz", + "integrity": "sha512-j1nvOQCZYSgp7HLmisnCXFTpVvFODiijQ9QHkORfGKWH6YDtskTEeCJS7eV545GZ9UBzrq0e2xsOd5QQ5PjIqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.29.7", + "@babel/generator": "^7.29.13", + "@babel/helper-compilation-targets": "^7.29.13", + "@babel/helper-module-transforms": "^7.29.13", + "@babel/helpers": "^7.29.13", + "@babel/parser": "^7.29.13", + "@babel/template": "^7.29.7", + "@babel/traverse": "^7.29.13", + "@babel/types": "^7.29.11", + "@jridgewell/remapping": "^2.3.5", + "convert-source-map": "^2.0.0", + "debug": "^4.1.0", + "gensync": "^1.0.0-beta.2", + "json5": "^2.2.3", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/babel" + } + }, + "node_modules/@babel/generator": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.14.tgz", + "integrity": "sha512-qSY56jgW5JnSXzuekLVil6zaOQxOCtOHidr65KkaMBw772IuAY28Qx4ZykAcDn8+FRF15qk80XzKwgSc/RYW6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.29.14", + "@babel/types": "^7.29.14", + "@jridgewell/gen-mapping": "^0.3.12", + "@jridgewell/trace-mapping": "^0.3.28", + "jsesc": "^3.0.2" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-compilation-targets": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.29.13.tgz", + "integrity": "sha512-8WxJ4/Vmes3ghacj8VOJy3NW8eyHiFY/4thU/LSBuBE470+igjR/j1ZTNn8fV5VdNrLx6iXUwig526UdOvfP0w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/compat-data": "^7.29.7", + "@babel/helper-validator-option": "^7.29.7", + "browserslist": "^4.24.0", + "lru-cache": "^5.1.1", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-globals": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.29.7.tgz", + "integrity": "sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-module-imports": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.29.7.tgz", + "integrity": "sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/traverse": "^7.29.7", + "@babel/types": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-module-transforms": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.29.14.tgz", + "integrity": "sha512-2XDvQVd9JESaOgGc4jT2/jquTAO7ppA5noTZQqH+MmZ89yjCzScLwtCPbWtkPZylL+TLWR49IwWmk+QkRR4GsA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-module-imports": "^7.29.7", + "@babel/helper-validator-identifier": "^7.29.7", + "@babel/traverse": "^7.29.14" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.14.tgz", + "integrity": "sha512-CXvKMFvM80ihI7Vox9jb+kQjnyjESQNPM+vB7U0Zz6TWuZA+Z/FL0QPMH300h33qJtIx+REeBhXqWOPW48TcAQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz", + "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-option": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.29.7.tgz", + "integrity": "sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helpers": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.14.tgz", + "integrity": "sha512-6E3Mi1r0B0umq6vmZa4/78q+64fqO2YY0THUdjDPKUCKhNb0yQy5NQIaPHCSD3ryTgiTss//P4JsWS80AsZ6LQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/template": "^7.29.7", + "@babel/types": "^7.29.14" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.14.tgz", + "integrity": "sha512-VL220vXuyO2z3rNIQwY7ftj9UwpqOt+33sH+sBWkOekbsSR2g7EEMnOx24ZlCH0xOA3DM/33SifVFGbnJD8r/w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.29.14" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/template": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz", + "integrity": "sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.29.7", + "@babel/parser": "^7.29.7", + "@babel/types": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/traverse": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.14.tgz", + "integrity": "sha512-RAdQJrBgmIH1FWvN0X+1hoDxzMzlP4cv/1Zi4dn4tG1H0cTb+rw7CzUxQJhp1f4ANd8j5vH3fy8BAWFGkBDEsA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.29.7", + "@babel/generator": "^7.29.14", + "@babel/helper-globals": "^7.29.7", + "@babel/parser": "^7.29.14", + "@babel/template": "^7.29.7", + "@babel/types": "^7.29.14", + "debug": "^4.3.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/types": { + "version": "7.29.14", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.14.tgz", + "integrity": "sha512-UjI/dKmwJwT9pOszJitq2G6EObZPnsZUfdCr92z2TlF3EZK9J3EdfOKUrCzHl6wFthbzwhzl1Soc/UIwxRiq6w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.29.14", + "@babel/helper-validator-identifier": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@cacheable/memory": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@cacheable/memory/-/memory-2.2.0.tgz", + "integrity": "sha512-CTLKqLItRCEixEAewD3/j9DB3/o96gpTPD4eJ1v+DGOlxZRZncRQkGYqqnAGCscYd6RNeXfGeiuCphsPtqyIfQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cacheable/utils": "^2.5.0", + "@keyv/bigmap": "^1.3.1", + "hookified": "^1.15.1", + "keyv": "^5.6.0" + } + }, + "node_modules/@cacheable/utils": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@cacheable/utils/-/utils-2.5.0.tgz", + "integrity": "sha512-buipgOVDkkPXNR5+xBpDw7Zk2n1EvU7qBJCNUcL7rhQ//kfpOXPAvQ511Os0vpLYJ1pZnvudNytkQt2hst3wqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "hashery": "^1.5.1", + "keyv": "^5.6.0" + } + }, + "node_modules/@codemirror/autocomplete": { + "version": "6.20.4", + "resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.4.tgz", + "integrity": "sha512-yF8RhOf2SXlg00+qtupzLhrglcas61boqaONiNcbPIebHCpJocpqTBA6dyrtUrQO47hqyTdeob/3XnYilT7TaQ==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.17.0", + "@lezer/common": "^1.0.0" + } + }, + "node_modules/@codemirror/commands": { + "version": "6.11.1", + "resolved": "https://registry.npmjs.org/@codemirror/commands/-/commands-6.11.1.tgz", + "integrity": "sha512-O/4hG3SC1YwcmQ0d2UVNDs+AsaNWd1iHVxbTeEBuqH+6bExAiPK3iS/BvpY6rZGURALv4ZD3sIgcCmRvw3ehBg==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.7.0", + "@codemirror/view": "^6.27.0", + "@lezer/common": "^1.1.0" + } + }, + "node_modules/@codemirror/lang-sql": { + "version": "6.10.0", + "resolved": "https://registry.npmjs.org/@codemirror/lang-sql/-/lang-sql-6.10.0.tgz", + "integrity": "sha512-6ayPkEd/yRw0XKBx5uAiToSgGECo/GY2NoJIHXIIQh1EVwLuKoU8BP/qK0qH5NLXAbtJRLuT73hx7P9X34iO4w==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@codemirror/language": { + "version": "6.13.1", + "resolved": "https://registry.npmjs.org/@codemirror/language/-/language-6.13.1.tgz", + "integrity": "sha512-zfvU2r3TyylQLMj/te+5CnQ0rSqZi8B1oTCBbQkagcLW4Xc6imab6qN+pEJhsuNOLaJqiRyBXp9UhWA1DhVvDw==", + "license": "MIT", + "dependencies": { + "@codemirror/state": "^6.0.0", + "@codemirror/streamparser": "^6.0.0", + "@codemirror/view": "^6.23.0", + "@lezer/common": "^1.5.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0", + "style-mod": "^4.0.0" + } + }, + "node_modules/@codemirror/lint": { + "version": "6.9.8", + "resolved": "https://registry.npmjs.org/@codemirror/lint/-/lint-6.9.8.tgz", + "integrity": "sha512-qNvtcE73xUto/D1RvtgSRI4A1Hg8ekxlvtZpjHpdpisLBnhyu82EUEJMEgaxkjuQCA8vqnrylENWKOsEDCOHcw==", + "license": "MIT", + "dependencies": { + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.42.0", + "crelt": "^1.0.5" + } + }, + "node_modules/@codemirror/search": { + "version": "6.7.2", + "resolved": "https://registry.npmjs.org/@codemirror/search/-/search-6.7.2.tgz", + "integrity": "sha512-gUYkYhT2+n/+VGZ+8EzE5WFkYZUZYm1VOKDudIsNqh42uRVQJ0a6Yss9sdKT3MeOYfuL1N6AZA57oza0Oyr0LA==", + "license": "MIT", + "dependencies": { + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.37.0", + "crelt": "^1.0.5" + } + }, + "node_modules/@codemirror/state": { + "version": "6.7.6", + "resolved": "https://registry.npmjs.org/@codemirror/state/-/state-6.7.6.tgz", + "integrity": "sha512-kAz+AncRtKuIknedxT1bq4XwXv4UowhbkHU1myPrtVb/jZtImWuV5BXzv5vK6i3kYACsdiZiQKFQQ5Mq7elW8w==", + "license": "MIT", + "dependencies": { + "@marijn/find-cluster-break": "^1.0.0" + } + }, + "node_modules/@codemirror/streamparser": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@codemirror/streamparser/-/streamparser-6.0.0.tgz", + "integrity": "sha512-JTFPF6xrfjt0mnfGPgzcLiMwYmvIyNaoizp8BYzv8FE8KrT6GBGDZ190rtt+O7Wke3gG/MFHyiY9YGNeimof4w==", + "license": "MIT" + }, + "node_modules/@codemirror/view": { + "version": "6.43.15", + "resolved": "https://registry.npmjs.org/@codemirror/view/-/view-6.43.15.tgz", + "integrity": "sha512-HHsfpqFeHyXLs983pSRe38Xajs0vFWZQ2BuX0m7Ki8w3jZ5iD8cuR3lBz2/5/X53Dhf32SBHKh6rtSTB6tKeGw==", + "license": "MIT", + "dependencies": { + "@codemirror/state": "^6.7.0", + "crelt": "^1.0.6", + "style-mod": "^4.1.0", + "w3c-keyname": "^2.2.4" + } + }, + "node_modules/@emnapi/core": { + "version": "2.0.0-beta.2", + "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-2.0.0-beta.2.tgz", + "integrity": "sha512-MzCVoWtcg4Pm2B3je5mMvYMvj3MmBKw+fU7vbsJc9/iT8ip6/eYIHo/Dsm/mr+wsHB6SEyJDuxB09Yy6r/8+4A==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "2.2.0", + "tslib": "^2.4.0" + } + }, + "node_modules/@emnapi/runtime": { + "version": "2.0.0-beta.2", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-2.0.0-beta.2.tgz", + "integrity": "sha512-JcrSPzPvZuNZvJqPTF9Fw25LbOJ8avzFVlaf2grmH4Cku0oGP47tRgqPZadcfj3YoZMHkFVnCYFbQM8I+i5QEw==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@emnapi/wasi-threads": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-2.2.0.tgz", + "integrity": "sha512-JP7OYH38Q7+pyTAe14raZHLQIK7BDKbdwji+Xi3pcd/6QkJYQH3SX4wu6EplGrGJWRepoNzedfm0G3B9Z4e9Rw==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@eslint-community/eslint-utils": { + "version": "4.10.1", + "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz", + "integrity": "sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg==", + "dev": true, + "license": "MIT", + "dependencies": { + "eslint-visitor-keys": "^3.4.3" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + }, + "peerDependencies": { + "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" + } + }, + "node_modules/@eslint-community/eslint-utils/node_modules/eslint-visitor-keys": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz", + "integrity": "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/@eslint-community/regexpp": { + "version": "4.12.3", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.12.3.tgz", + "integrity": "sha512-R76UKbvsqI68DJJVTVyqFKqU98CN4+B+acxNfEA2IFarSzP0SjtKf/3+fFiXzTyv5Fj3PxLkGHe2wnVWWMxobQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.0.0 || ^14.0.0 || >=16.0.0" + } + }, + "node_modules/@eslint/config-array": { + "version": "0.23.6", + "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.23.6.tgz", + "integrity": "sha512-WrTH7nioI9QPY4NZGnsywmecswJdgeq4BCM76qok9VgjTO29ZgUzUvcuJLVPYVQM4uDbaPBU0M33R9DIxI8X3w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@eslint/object-schema": "^3.0.5", + "debug": "^4.3.1", + "minimatch": "^11.0.5" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + } + }, + "node_modules/@eslint/config-helpers": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.7.0.tgz", + "integrity": "sha512-DObd/KKUsU+FaFv4PLxSRenpXfQWmPXXP3pPZ6/K1PCrMu2vQpMDMuQe/BqYeoLcz8ro0bVDF1RxOJgfVEdhUw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@eslint/core": "^1.2.1" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + } + }, + "node_modules/@eslint/core": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@eslint/core/-/core-1.2.1.tgz", + "integrity": "sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@types/json-schema": "^7.0.15" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + } + }, + "node_modules/@eslint/js": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-10.0.1.tgz", + "integrity": "sha512-zeR9k5pd4gxjZ0abRoIaxdc7I3nDktoXZk2qOv9gCNWx3mVwEn32VRhyLaRsDiJjTs0xq/T8mfPtyuXu7GWBcA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://eslint.org/donate" + }, + "peerDependencies": { + "eslint": "^10.0.0" + }, + "peerDependenciesMeta": { + "eslint": { + "optional": true + } + } + }, + "node_modules/@eslint/object-schema": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-3.0.5.tgz", + "integrity": "sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + } + }, + "node_modules/@eslint/plugin-kit": { + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.7.3.tgz", + "integrity": "sha512-IkO+/KEUvwbVpiURZg+P7zF74z5Jxe0UgJxVni+RtoHQ6IZieXaO02kmadomap/q+l6bc/jdPGGqTjhuZnuz1Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@eslint/core": "^1.2.1", + "levn": "^0.4.1" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + } + }, + "node_modules/@exodus/bytes": { + "version": "1.16.0", + "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.16.0.tgz", + "integrity": "sha512-IcpW84uEn3N7ETtNZMlxKhfl6Pec8rUNGOTBtWbK1FKhJxIFAptZyVrvVRVBimAJxJCgc3PxepxkdWWG4DVzfA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^20.19.0 || ^22.12.0 || >=24.0.0" + }, + "peerDependencies": { + "@noble/hashes": "^1.8.0 || ^2.0.0" + }, + "peerDependenciesMeta": { + "@noble/hashes": { + "optional": true + } + } + }, + "node_modules/@humanfs/core": { + "version": "0.19.2", + "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.2.tgz", + "integrity": "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@humanfs/types": "^0.15.0" + }, + "engines": { + "node": ">=18.18.0" + } + }, + "node_modules/@humanfs/node": { + "version": "0.16.8", + "resolved": "https://registry.npmjs.org/@humanfs/node/-/node-0.16.8.tgz", + "integrity": "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@humanfs/core": "^0.19.2", + "@humanfs/types": "^0.15.0", + "@humanwhocodes/retry": "^0.4.0" + }, + "engines": { + "node": ">=18.18.0" + } + }, + "node_modules/@humanfs/types": { + "version": "0.15.0", + "resolved": "https://registry.npmjs.org/@humanfs/types/-/types-0.15.0.tgz", + "integrity": "sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=18.18.0" + } + }, + "node_modules/@humanwhocodes/module-importer": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz", + "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=12.22" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/nzakas" + } + }, + "node_modules/@humanwhocodes/retry": { + "version": "0.4.3", + "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.3.tgz", + "integrity": "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=18.18" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/nzakas" + } + }, + "node_modules/@isaacs/nonrecursive-glob-match": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@isaacs/nonrecursive-glob-match/-/nonrecursive-glob-match-1.1.0.tgz", + "integrity": "sha512-GPm/Dbvk5RLmhRnxXIa7nTpK0xtl4E0wj0MslsuNiJ1FIROU+2+9lgUC/dgF7Ey4QCWhfEsgxilMRMCdHPfDfw==", + "dev": true, + "license": "BlueOak-1.0.0" + }, + "node_modules/@jridgewell/gen-mapping": { + "version": "0.3.13", + "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz", + "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.0", + "@jridgewell/trace-mapping": "^0.3.24" + } + }, + "node_modules/@jridgewell/remapping": { + "version": "2.3.5", + "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz", + "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.5", + "@jridgewell/trace-mapping": "^0.3.24" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.3.tgz", + "integrity": "sha512-lhTtjtoEArWBjismtfS761S9Hlyn+nIZqOZVYoZ1Xn82PMNMVnk+jj/NhC4fAXGTs7ydONcJiR5vyQBTMDu27g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.31", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", + "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.1.0", + "@jridgewell/sourcemap-codec": "^1.4.14" + } + }, + "node_modules/@keyv/bigmap": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/@keyv/bigmap/-/bigmap-1.3.1.tgz", + "integrity": "sha512-WbzE9sdmQtKy8vrNPa9BRnwZh5UF4s1KTmSK0KUVLo3eff5BlQNNWDnFOouNpKfPKDnms9xynJjsMYjMaT/aFQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "hashery": "^1.4.0", + "hookified": "^1.15.0" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "keyv": "^5.6.0" + } + }, + "node_modules/@keyv/serialize": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@keyv/serialize/-/serialize-1.1.1.tgz", + "integrity": "sha512-dXn3FZhPv0US+7dtJsIi2R+c7qWYiReoEh5zUntWCf4oSpMNib8FDhSoed6m3QyZdx5hK7iLFkYk3rNxwt8vTA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@lezer/common": { + "version": "1.5.5", + "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.5.tgz", + "integrity": "sha512-Pw7PVCndruF1pb3ebCxpSVpkMHSDjwRCLcTRw+RizUKco5QbWylwq2g4lnG/RYN7yTTQDXE9F77MwtkAyphrjg==", + "license": "MIT" + }, + "node_modules/@lezer/highlight": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/@lezer/highlight/-/highlight-1.2.5.tgz", + "integrity": "sha512-O1GMVKgtf5YspFaRzpmqkVgMtIk2HG9uMAbH6wdAIdNh3TVzCsch/+cRi+6l2//UGDKe6NB9BW3cvuR5ezMQ0w==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.3.0" + } + }, + "node_modules/@lezer/lr": { + "version": "1.4.12", + "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.12.tgz", + "integrity": "sha512-On9HU4oMMiHPMkQDgoTnGahjgG5n/MkN38CgG77sMraKLL+3JBbeQNi1FcCXV9QRqwF9/BUXP3caHyJC1fBOTQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.0.0" + } + }, + "node_modules/@marijn/find-cluster-break": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@marijn/find-cluster-break/-/find-cluster-break-1.0.4.tgz", + "integrity": "sha512-Wy0V7+SGUjnF9/TkiM1hKVDPj7jKXduPNboMVtHTA8dySMURWqfg/JZ9E2Sq8JgSJmkl7k7Qe9FLeMSrSraWmQ==", + "license": "MIT" + }, + "node_modules/@napi-rs/wasm-runtime": { + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.2.6.tgz", + "integrity": "sha512-mRyDmEw9/fCDXCGfL1sbgIw/GUK0PVxRW4YwgPN61F3LQ+fSyoBFarJVzgGyhF6kRzEQZ0FejDqm4WLXSeqQmw==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@tybys/wasm-util": "^0.10.3" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=23.5.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Brooooooklyn" + }, + "peerDependencies": { + "@emnapi/core": "^1.7.1 || 2.0.0-beta.2", + "@emnapi/runtime": "^1.7.1 || 2.0.0-beta.2" + } + }, + "node_modules/@oxc-project/types": { + "version": "0.156.0", + "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.156.0.tgz", + "integrity": "sha512-1Duyg48TdJNdyhEB8Xn1L36bT9Pv6GUtlKjHxOys8xkaF/rQq3XJE+bAurSK/AgIz5mGFsb77cn9Pb20+WCScw==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/oxc-project" + } + }, + "node_modules/@rolldown/binding-android-arm-eabi": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.19.tgz", + "integrity": "sha512-e+Ebe0WT+9tbXmNKPIiC8YrWAHYwug3m6i4p3rZGGulfZri1jtI4HslT+OZnFf/OIHowWF71DTlHwXBP2SiA7A==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-android-arm64": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.19.tgz", + "integrity": "sha512-hOombrTJ+szt2ciEzS7oCA78lMPBgF5UMQWCJIyNfnrI7GLl8HYoFqCnpL2gcPOaXMqryGCU5ExdQKyDDcC+yA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-darwin-arm64": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.19.tgz", + "integrity": "sha512-XoMA2pwCKGTQzUjPgtRwkedH4WmXhdIPKT6l6oOxd1PUbNodGI6DcBekgN7EC//+x3pfBYX/qL1gNmZAqivw5g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-darwin-x64": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.19.tgz", + "integrity": "sha512-zo8EsSSwMZCY/e+fRnGaX02YGgvJD0yvhNi/9hpGPA2MJ9ZF8dPCw75UGfpI6OpQ/myR/dIYmogRvqiZD0TrXg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-freebsd-x64": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.19.tgz", + "integrity": "sha512-O8ISAOfI1nj7AuBPd30FSF47z7f7lzlk5poQVGgiikvQuGEBFYvW8ki+UEnT+YJPnNGjQzn304klt4O9FUE7mA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-arm-gnueabihf": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.19.tgz", + "integrity": "sha512-/lYCba5NO0yq4S0jGMH8QTBtkvQxoXjoQWzF5BcWp9MjB9jxVRD1GQDNofkVjcOj30DWyhLIN/4Oe60JKzaONw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-arm64-gnu": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.19.tgz", + "integrity": "sha512-pm/apFMBnSbFb3O6nG5pHO1iqHhZrjGDFEjSm+ot9J17XXPvH9L90y5h+jgfHCE+Qdlsvy8qKEcU4VKxgjD+vA==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-arm64-musl": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.19.tgz", + "integrity": "sha512-K1SmQp3FFichn8oqrNIwvFoZ5wcvjC7goBzpaMNvLf9FZc+QB/QvLmnpJZgAAGHiD980tP8FZZnXk2K94rvlxg==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-ppc64-gnu": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.19.tgz", + "integrity": "sha512-I0xwD57jP/3A7+5UPZin2w8Y7XHEmEM5zqpYZOcQ45MlNW6tUJUziymV3yRr7rL4vwyfEcRsRksC4a7Kc08p5Q==", + "cpu": [ + "ppc64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-s390x-gnu": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.19.tgz", + "integrity": "sha512-BrtEHT24SNXj9HiXqy+s/kXiSiQGt6EKCPUlRirAoIioVxKGnbXBUEkbZASAei7iZJB0/Ynm+0JP00Ipx7AnSw==", + "cpu": [ + "s390x" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-x64-gnu": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.19.tgz", + "integrity": "sha512-rm75/9DkHKeU2WnA8w4X94WGYgLlDCFCfkQC+4bguVJmC/jvDRv2B+2wLOYhyE0fVuv7//Ckk39OoOufyCu76Q==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-linux-x64-musl": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.19.tgz", + "integrity": "sha512-irh/4+iYFM4GAzpluDErgjz89bj6NDtqqMAG/6O1LG38Ed3NpyebzCpcVNkFW8uhy+/3/BocUvnXDR33CXWe9A==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-openharmony-arm64": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.19.tgz", + "integrity": "sha512-+KWTWNoPt+CfSq94CiceWu3yPE+QzkaG+phPyz9G60tmZLwfQkcA4AeksafzvJAw4pvg1mcd5a1TkUqVv0s4JA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-wasm32-wasi": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.2.19.tgz", + "integrity": "sha512-7EH+skOsl5qpWnK0vzamgJFhOv1cwxQpsxm8tI883K9fur5c27p8q87fzEO6BbBPabA2/+s/zR63/pLc137iOg==", + "cpu": [ + "wasm32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "2.0.0-beta.2", + "@emnapi/runtime": "2.0.0-beta.2", + "@napi-rs/wasm-runtime": "1.2.6" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=23.5.0" + } + }, + "node_modules/@rolldown/binding-win32-arm64-msvc": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.19.tgz", + "integrity": "sha512-3Q1Yg1Q7tEvBWoZf5rFvG/GKZQPgwfru+p4wBajDfJFBs0SHCpL++dfTjW9gyAKd1T7ZpIYvdaUax7Pa/IhFVQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/binding-win32-x64-msvc": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.19.tgz", + "integrity": "sha512-y/sqRRc6d7hECzOFc5n3LSeqctmIp9mMjY1Kq4s14uLPd/LZ4z7i1zrW6fMtp2mPeuQIC4e6ULMcwQzMomqQag==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rolldown/pluginutils": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.1.1.tgz", + "integrity": "sha512-glFIJDvLNDtJhT9qrMFWLPbvS+skxgt4L0K8Ei2YtnhPysAJnsI7nyxSJxKj4ADeKX0OLjC4ntRkwpLOoS3rwA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@tailwindcss/node": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.3.5.tgz", + "integrity": "sha512-yT53FzV4ke0cr/BguDxhWMpm5MJu1O2muzk+tKw6lKHjODAsYArBbWwFbJiaksfzFv1tpkO9QHGzmfs1hJT66g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/remapping": "^2.3.5", + "enhanced-resolve": "^5.24.5", + "jiti": "^2.7.0", + "lightningcss": "1.33.0", + "magic-string": "^1.1.0", + "source-map-js": "^1.2.1", + "tailwindcss": "4.3.5" + } + }, + "node_modules/@tailwindcss/oxide": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.3.5.tgz", + "integrity": "sha512-PynqGLZsZvwM9tqD/CUxkOIfyd6K5elZ2MooauzJryP/UqXYgi3yYbtt3N0Xe+MHV/eFKPFQCEfIKAqlAS1CBg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 20" + }, + "optionalDependencies": { + "@tailwindcss/oxide-android-arm64": "4.3.5", + "@tailwindcss/oxide-darwin-arm64": "4.3.5", + "@tailwindcss/oxide-darwin-x64": "4.3.5", + "@tailwindcss/oxide-freebsd-x64": "4.3.5", + "@tailwindcss/oxide-linux-arm-gnueabihf": "4.3.5", + "@tailwindcss/oxide-linux-arm64-gnu": "4.3.5", + "@tailwindcss/oxide-linux-arm64-musl": "4.3.5", + "@tailwindcss/oxide-linux-x64-gnu": "4.3.5", + "@tailwindcss/oxide-linux-x64-musl": "4.3.5", + "@tailwindcss/oxide-wasm32-wasi": "4.3.5", + "@tailwindcss/oxide-win32-arm64-msvc": "4.3.5", + "@tailwindcss/oxide-win32-x64-msvc": "4.3.5" + } + }, + "node_modules/@tailwindcss/oxide-android-arm64": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.3.5.tgz", + "integrity": "sha512-Se0z5xMqcSQanJD1IYmO0cGpK3iv0fp3ZsIT7xRJZ1Da5PghvNoc46zz4jIQn+aan3dV9T8AermFNN9QPmsh0Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-darwin-arm64": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.3.5.tgz", + "integrity": "sha512-UPrgTDuUbvmqGMZuCnmI3FKee/tYKzKdp00/kuB4oSGB213VYg8QTdF7lVhnPoBXq/mIfJ+ILoBFqNOboWcMwQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-darwin-x64": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.3.5.tgz", + "integrity": "sha512-E+p7HEtjI0b8D7kbbWxH067cGui6d4c79COGko9fAPVE3rwc1E7ld2HFCbaG86AOGWS5VKQYqZOaf38ya4uxTQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-freebsd-x64": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.3.5.tgz", + "integrity": "sha512-yWEWcWyAG7rWOcTpJTjdhQ3pcaFY2h+0bqTRfgU3G2fz87ZU3AKdvdZKhslD+kyHnjBUWKvNdRYwIYC5dI1tIg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-linux-arm-gnueabihf": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.3.5.tgz", + "integrity": "sha512-WmeVjtJhZlr+smpqcdR2kQkkn6arHIJnUIBxTO2EJcTLGY1ecVXNo2hbSn8xc0IH2aEtys936iMWKGyj0GaKnA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-linux-arm64-gnu": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.3.5.tgz", + "integrity": "sha512-DTCSyucc6ShMp1QMqV5R94Z7xlgNgUzkGmFF1rL5HH2Qjy4eSmEqy+YLGkqqYvWa4sILtgrBt1JjRKbneQtiFQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-linux-arm64-musl": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.3.5.tgz", + "integrity": "sha512-H9lsvO4x9E4nE4Hi8h7NHHw0O/kcVSu+iOyFHNGdYzazGgDjFHZbE6S3hQ8kMcbNXSBlMdNi67LV5EVqtpaJtw==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-linux-x64-gnu": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.3.5.tgz", + "integrity": "sha512-4uxQvtBvPuIdl13WfUBj9xMZHH14PtHZ8OZdtLmdyDtG66sCa1t599NZT+jagkUzRtWhuul1qRZQ1nAJscXN5g==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-linux-x64-musl": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.3.5.tgz", + "integrity": "sha512-0JQAzs7jwbA7O6+z/adU+Jk3AXwsu3npAhtr5escXS7TqEqWcaDV7qHuI+0Vy/KQRuVGnLQREcSJWYauyV3oqg==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.3.5.tgz", + "integrity": "sha512-OJhFmlEfdzMr+avACdi40RPtnkW0B6hXyxL/8r+tnEHBWZji36CYRjEXrrvgBmaYsD3oEOBqwYFRKsYvzFe7Bw==", + "bundleDependencies": [ + "@napi-rs/wasm-runtime", + "@emnapi/core", + "@emnapi/runtime", + "@tybys/wasm-util", + "@emnapi/wasi-threads", + "tslib" + ], + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "^1.11.3", + "@emnapi/runtime": "^1.11.3", + "@emnapi/wasi-threads": "^1.2.3", + "@napi-rs/wasm-runtime": "^1.2.2", + "@tybys/wasm-util": "^0.10.3", + "tslib": "^2.8.1" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=23.5.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": { + "version": "1.11.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "1.2.3", + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": { + "version": "1.11.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": { + "version": "1.2.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": { + "version": "1.2.2", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@tybys/wasm-util": "^0.10.3" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=23.5.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Brooooooklyn" + }, + "peerDependencies": { + "@emnapi/core": "^1.7.1 || ^2.0.0-alpha.3", + "@emnapi/runtime": "^1.7.1 || ^2.0.0-alpha.3" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": { + "version": "0.10.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": { + "version": "2.8.1", + "dev": true, + "inBundle": true, + "license": "0BSD", + "optional": true + }, + "node_modules/@tailwindcss/oxide-win32-arm64-msvc": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.3.5.tgz", + "integrity": "sha512-9o8jgthi+QE5eandnboiJT64VQfnIArfZzSTdgbhEK5aafdiu2jTW9Honi/mwYHxBZuH1vAC57IFyrh+0iK5Gg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/oxide-win32-x64-msvc": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.3.5.tgz", + "integrity": "sha512-XiKFfIy1RWe7qK4WqByxNW7Oz1/nkOy8o/BWhHminyV1PmpUd8Eedj5v2A8h2kpqeVlz6xRnwk9Fr/ZXNLcZfg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 20" + } + }, + "node_modules/@tailwindcss/vite": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@tailwindcss/vite/-/vite-4.3.5.tgz", + "integrity": "sha512-BCNiY0a1ZjdOHVqw7kyb7U72BwfMF3dfUuN+tQsLWky/J5JOI/r7abibglXfygrZhVO/3u3V+E25kkKTeMkXaQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@tailwindcss/node": "4.3.5", + "@tailwindcss/oxide": "4.3.5", + "tailwindcss": "4.3.5" + }, + "peerDependencies": { + "vite": "^5.2.0 || ^6 || ^7 || ^8" + } + }, + "node_modules/@tanstack/react-store": { + "version": "0.11.2", + "resolved": "https://registry.npmjs.org/@tanstack/react-store/-/react-store-0.11.2.tgz", + "integrity": "sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==", + "license": "MIT", + "dependencies": { + "@tanstack/store": "0.11.2", + "use-sync-external-store": "^1.6.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/@tanstack/react-table": { + "version": "9.3.1", + "resolved": "https://registry.npmjs.org/@tanstack/react-table/-/react-table-9.3.1.tgz", + "integrity": "sha512-E6Ya5TnY6EaGyZYIUqig/29Lr/gJSAubQkLJFqiWkUl5nRCr0Xr9hvJot+NiRTtG+TzGxHTiqUW3bnLtQxlHug==", + "license": "MIT", + "dependencies": { + "@tanstack/react-store": "^0.11.2", + "@tanstack/table-core": "9.3.1" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "peerDependencies": { + "react": ">=18" + } + }, + "node_modules/@tanstack/react-virtual": { + "version": "3.14.26", + "resolved": "https://registry.npmjs.org/@tanstack/react-virtual/-/react-virtual-3.14.26.tgz", + "integrity": "sha512-HUDlfsrYH6ko5xH56L62Mcl/uzT+AGVNMHFuDNqDJMdZWc1AQa2oeVKNUvZ/RWBZQ4TYtyQerFrNvLnp39h65A==", + "license": "MIT", + "dependencies": { + "@tanstack/virtual-core": "3.19.11" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/@tanstack/store": { + "version": "0.11.2", + "resolved": "https://registry.npmjs.org/@tanstack/store/-/store-0.11.2.tgz", + "integrity": "sha512-sJ4mjol8uQsHV0gOJzzjwXfh2Fwm+Sz0+8deqiTm4jGbMdjzNSW+xZCFm0kUa870uhd8yi+DpKnZb5Kc4apa0Q==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + } + }, + "node_modules/@tanstack/table-core": { + "version": "9.3.1", + "resolved": "https://registry.npmjs.org/@tanstack/table-core/-/table-core-9.3.1.tgz", + "integrity": "sha512-zQvlxSNi2qGM3L4jh85Z6hqMfdIR5qOfD9KHOU32nuKFJGN0RlJ7UvV1lsPb1fPVhpFYI0VP3jJGxLdLDpTKjQ==", + "license": "MIT", + "dependencies": { + "@tanstack/store": "^0.11.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + } + }, + "node_modules/@tanstack/virtual-core": { + "version": "3.19.11", + "resolved": "https://registry.npmjs.org/@tanstack/virtual-core/-/virtual-core-3.19.11.tgz", + "integrity": "sha512-/5iHb0RHBvj8Di59FDs4ESNm45jls33aZAi4zccVXZjc/6ZvwQP6nzEYeT6weXjTf9E6/vrp2JhYWRyO+ZP13A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + } + }, + "node_modules/@tauri-apps/api": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.12.5.tgz", + "integrity": "sha512-G9QIMt5fzED+aS4QhVK3w1HWLKpLIwH/MnpCr9z1ugGEHnS2ORmqrLkc0uALOjRK4qXJy+4Yiw8LDl/KicC1Hg==", + "license": "Apache-2.0 OR MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/tauri" + } + }, + "node_modules/@tauri-apps/cli": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli/-/cli-2.12.5.tgz", + "integrity": "sha512-Dm8s/4aiE52HsBh+Gz3uSrh+fEykRICA1VoAnQA80IqHoTRncPg+q4rGvuhmyNsHUPg3QrPjUrTUSfWmXLVVEw==", + "dev": true, + "license": "Apache-2.0 OR MIT", + "bin": { + "tauri": "tauri.js" + }, + "engines": { + "node": ">= 10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/tauri" + }, + "optionalDependencies": { + "@tauri-apps/cli-darwin-arm64": "2.12.5", + "@tauri-apps/cli-darwin-x64": "2.12.5", + "@tauri-apps/cli-linux-arm-gnueabihf": "2.12.5", + "@tauri-apps/cli-linux-arm64-gnu": "2.12.5", + "@tauri-apps/cli-linux-arm64-musl": "2.12.5", + "@tauri-apps/cli-linux-riscv64-gnu": "2.12.5", + "@tauri-apps/cli-linux-x64-gnu": "2.12.5", + "@tauri-apps/cli-linux-x64-musl": "2.12.5", + "@tauri-apps/cli-win32-arm64-msvc": "2.12.5", + "@tauri-apps/cli-win32-ia32-msvc": "2.12.5", + "@tauri-apps/cli-win32-x64-msvc": "2.12.5" + } + }, + "node_modules/@tauri-apps/cli-darwin-arm64": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-arm64/-/cli-darwin-arm64-2.12.5.tgz", + "integrity": "sha512-VVvBRBdTFF7BP7RqGeItp9yDiyXj0DI1laRCEN2q6GLrNkw4wrHeWAxHp23PwtQtn/XET+yTN1jOKrq+Yor5PQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-darwin-x64": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.12.5.tgz", + "integrity": "sha512-A84QYNj93kaG06N2mIFBRZM/X3lf9TyAVQeQwOmP2AJZ2wCt1WLDJgHRCvjeJmwJjJ5Ud0jUbIKbXg8NEGvsVQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-linux-arm-gnueabihf": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.12.5.tgz", + "integrity": "sha512-tb/5xG5HV6CJR9AZBmTyI2GCi05vcH8XUjUIjBquAx7x+AE4f1vMWngvq7JW2AqYK8nNl79LJH1GR9Hf5QQc5g==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-linux-arm64-gnu": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.12.5.tgz", + "integrity": "sha512-Vb7SlbIWlmIqekfsGYT64wH1cQNg5MET8XFyT6pUlVJ7Y/z6LsOIh4MUal0Z5FCPL83GMuEUNxpYUHpt36teHQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-linux-arm64-musl": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.12.5.tgz", + "integrity": "sha512-b/YfVGueoTOtENQHY1STBF9XlU4uZDtOiMUErp2Nao/YrDWCKggjxxBZU3ycbeDWUYxl8U8M9seE4HYag1xjiQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-linux-riscv64-gnu": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.12.5.tgz", + "integrity": "sha512-/EXbTfE9FM9GKSSRL9YTRHcMglTVNzbcwegXM0MBR3ozVgoE+pFq46Ej/InJBs1l+sjSpu6jyi38MZ+xyU/3NQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-linux-x64-gnu": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.12.5.tgz", + "integrity": "sha512-OIun574QsULxaZ5SmPDX4D8bO95RBmYJshu8yGFy0RSyCMKEs/y+o3BThot4fbCv4ttC1Tq6Hzt0QRHXCIgp7w==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-linux-x64-musl": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.12.5.tgz", + "integrity": "sha512-GDzWcb/6OzJrHnVGQ/n3XndLan67bZ7cu4zJN9+zFmV10nBgKz5jDDm8sRQO4sGb7bu6Ztiy+Al2XY2ptRY0RQ==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-win32-arm64-msvc": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.12.5.tgz", + "integrity": "sha512-61KCX5vo0vex7P/P7sbXdfFhHqs+rFaG+UXK/UBwz/VlLveDx6vgpHkF+rfUIfCqj0VvLArpxR3+rQIzRwxKgw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-win32-ia32-msvc": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.12.5.tgz", + "integrity": "sha512-mGujjR/MlXwJiQcue4wlXrBYlIEdDCoap0g+GNPlLCb75ilSbWMC8qTsXVuGcLIMumIJvc2v+veDnCHnels/Zg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tauri-apps/cli-win32-x64-msvc": { + "version": "2.12.5", + "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.12.5.tgz", + "integrity": "sha512-o1+EOjvi/nFwKx5XamCXSr+GUr2ko8TH7+0wnWuZjE+lZwE+/VWCbE49HPHa3/V59M3bJ0dlK1yhogGQ15OVPg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0 OR MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@tybys/wasm-util": { + "version": "0.10.5", + "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.5.tgz", + "integrity": "sha512-dOGOPxlaNV+G046mZzN+9C0dAcQZeSKcXiVaM0TYy/LM4ttTmgSBDxYfovcYI8Em3+eAbiAYpvWLOv8+ZVRJKA==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@types/chai": { + "version": "5.2.3", + "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz", + "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/deep-eql": "*", + "assertion-error": "^2.0.1" + } + }, + "node_modules/@types/deep-eql": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz", + "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/esrecurse": { + "version": "4.3.1", + "resolved": "https://registry.npmjs.org/@types/esrecurse/-/esrecurse-4.3.1.tgz", + "integrity": "sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/estree": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.10.tgz", + "integrity": "sha512-lTyOMnOcmRBzdCv6/4zUZCrEhV0xrqQiUZBZtVcbmLHBXKLnN8q89v/wKRF/Q0HbwVsqbIG3o5HDoFl9sduM+g==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/json-schema": { + "version": "7.0.15", + "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz", + "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "24.19.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.19.2.tgz", + "integrity": "sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": ">=7.24.0 <7.24.7" + } + }, + "node_modules/@types/react": { + "version": "19.3.0", + "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz", + "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==", + "dev": true, + "license": "MIT", + "dependencies": { + "csstype": "^3.2.2" + } + }, + "node_modules/@types/react-dom": { + "version": "19.3.0", + "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.3.0.tgz", + "integrity": "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "@types/react": "^19.3.0" + } + }, + "node_modules/@typescript-eslint/eslint-plugin": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.73.0.tgz", + "integrity": "sha512-UkygMFer53Yzn29MCYFTHf34hGXf5KJhiDWfIm1tXtXRrym1CS6l5H9Y3yCtPWChpC0/f93H88gdj8tN0dd4kw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/regexpp": "^4.12.2", + "@typescript-eslint/scope-manager": "8.73.0", + "@typescript-eslint/type-utils": "8.73.0", + "@typescript-eslint/utils": "8.73.0", + "@typescript-eslint/visitor-keys": "8.73.0", + "ignore": "^7.0.5", + "natural-compare": "^1.4.0", + "ts-api-utils": "^2.5.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "@typescript-eslint/parser": "^8.73.0", + "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/@typescript-eslint/eslint-plugin/node_modules/ignore": { + "version": "7.0.16", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.16.tgz", + "integrity": "sha512-52N+Y4HRMOJmbLmr+DqO4iSRyyB7N52gm7PWCT6h0p978+oKbqHCB7gIJIwZvBUsjlSdWbrBFqUSmIFNZMpn0A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/@typescript-eslint/parser": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.73.0.tgz", + "integrity": "sha512-AuL45bVcmssHfZ3Di3cs9Q0l4gBm4ZFVrJOQEE7VpqW+PVgQaEwSwazz4TVIiFabXkk6U51EprYDwqw+HR8ePw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/scope-manager": "8.73.0", + "@typescript-eslint/types": "8.73.0", + "@typescript-eslint/typescript-estree": "8.73.0", + "@typescript-eslint/visitor-keys": "8.73.0", + "debug": "^4.4.3" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/@typescript-eslint/project-service": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.73.0.tgz", + "integrity": "sha512-/pEf8Rc4Mjk+qJnY0uO1+Gadeal8uv50xpuic+srG2vIVatA0XxvWMUeMtFvs6OCHqftiQ7/+qH4aehG5stzIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/tsconfig-utils": "^8.73.0", + "@typescript-eslint/types": "^8.73.0", + "debug": "^4.4.3" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/@typescript-eslint/scope-manager": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.73.0.tgz", + "integrity": "sha512-/TjD738Iq2rzj5z0ixVOi+TsvgjAzZPLPaH1yWdDBytR/HTR5gMpyYWZeCe5WTQZLwk3ho8AV7U3muoQCRtXBQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "8.73.0", + "@typescript-eslint/visitor-keys": "8.73.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@typescript-eslint/tsconfig-utils": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.73.0.tgz", + "integrity": "sha512-lmtCFOfYaJfpqZywGuXi4FpNtE+NQ+YLe3T0K9rtEDcW8ZuGWvfI++pj8r05sYMI8vWT2CYK4rWyedmD6Rp4og==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/@typescript-eslint/type-utils": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.73.0.tgz", + "integrity": "sha512-MOC9i4xy1F7KcDde7Ip8jf1SrRiALb2Km4UWxGNjUE2YlhjIEo1ayE27GHIwIQyfWuHTmEonQT14uyurlyC6aA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "8.73.0", + "@typescript-eslint/typescript-estree": "8.73.0", + "@typescript-eslint/utils": "8.73.0", + "debug": "^4.4.3", + "ts-api-utils": "^2.5.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/@typescript-eslint/types": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.73.0.tgz", + "integrity": "sha512-O/1ytYzflF16QDKXx4/qOXg1IuZp+n7hr9t+S0nv7N/2Tl8rJiNCshztV1gcSUvHbPtoX3+zmNbtSAyVbzxVfw==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@typescript-eslint/typescript-estree": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.73.0.tgz", + "integrity": "sha512-InjlBkSdWceIwIBWSwS3ENUp+i0O02PGX3Zv2wnihWJC1WDVGvG7mTHuf8b57uAaITj94d6tRPDH+sUEtXdRQQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/project-service": "8.73.0", + "@typescript-eslint/tsconfig-utils": "8.73.0", + "@typescript-eslint/types": "8.73.0", + "@typescript-eslint/visitor-keys": "8.73.0", + "debug": "^4.4.3", + "minimatch": "^11.0.1", + "semver": "^7.7.3", + "tinyglobby": "^0.2.15", + "ts-api-utils": "^2.5.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "@typescript/native": "npm:typescript@>=7.1.0-dev.20261009.1 || >=7.1.0-beta <7.1.0-dev", + "typescript": ">=4.8.4 <6.1.0" + }, + "peerDependenciesMeta": { + "@typescript/native": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/typescript-estree/node_modules/semver": { + "version": "7.8.6", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz", + "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/@typescript-eslint/utils": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.73.0.tgz", + "integrity": "sha512-j2SVJJvVkXdUL0WcEzo4vEH1mO1vIi8KlVukcYA2MgMZvYN2LlZR4PmsW+GTSxSW24j6Q/EP7+MOifLtg5hmsA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/eslint-utils": "^4.9.1", + "@typescript-eslint/scope-manager": "8.73.0", + "@typescript-eslint/types": "8.73.0", + "@typescript-eslint/typescript-estree": "8.73.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/@typescript-eslint/visitor-keys": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.73.0.tgz", + "integrity": "sha512-k4lsFVpRZICbltkIEEH4hZRkwXkqDF1GHBpClKQOHQY+RkoZAAuyc1ci3I6p+CB6v3U4jaHIUshc4RzzQXZWLg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "8.73.0", + "eslint-visitor-keys": "^5.0.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@vitejs/plugin-react": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-6.3.0.tgz", + "integrity": "sha512-H9E955aVvD2F4zNHCw4eIZbIfF6xKldlh7MNu+hSU7xwQzh65lI/N+CJWqmfhi0PEjDXIt/H7T7J/4wU63KJiw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@rolldown/pluginutils": "^1.0.1" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "peerDependencies": { + "@rolldown/plugin-babel": "^0.1.7 || ^0.2.0 || ^0.3.0", + "babel-plugin-react-compiler": "^1.0.0", + "oxc-transform-react": ">=0.152.0 <0.157.0", + "vite": "^8.0.0" + }, + "peerDependenciesMeta": { + "@rolldown/plugin-babel": { + "optional": true + }, + "babel-plugin-react-compiler": { + "optional": true + }, + "oxc-transform-react": { + "optional": true + } + } + }, + "node_modules/@vitest/mocker": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-5.1.0.tgz", + "integrity": "sha512-5umB9/jlWcqVS6fsrFmv5Gdnpu6wAUio/lEOwAmvB7v+lFo/IW2B9FhAD0p19GCULTgMzLCdUmuCDCnAzWgppQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.31", + "@vitest/spy": "5.1.0", + "estree-walker": "^3.0.3", + "magic-string": "^1.4.3" + }, + "funding": { + "url": "https://opencollective.com/vitest" + }, + "peerDependencies": { + "msw": "^2.4.9 || ^3.0.0", + "vite": "^6.0.0 || ^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "msw": { + "optional": true + }, + "vite": { + "optional": true + } + } + }, + "node_modules/@vitest/spy": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-5.1.0.tgz", + "integrity": "sha512-2DPO5OMHWKrBngC+fCmTQqemNF0gidRhp3lxbBmRhW+M1XJrfgPpqNqWVevXtn2f2ufD5ZaR1B6B641aAlcX5A==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/acorn": { + "version": "8.19.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz", + "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==", + "dev": true, + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/ajv": { + "version": "6.15.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz", + "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/assertion-error": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz", + "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + } + }, + "node_modules/balanced-match": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", + "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "18 || 20 || >=22" + } + }, + "node_modules/baseline-browser-mapping": { + "version": "2.11.38", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.38.tgz", + "integrity": "sha512-rMgy5YW7x28SMfXHLlVZDBqlWzYZ0x2rVR/6FWrNBF0chjigARK1H6nM0hKA1Um3kPOlkQFVtjJs00d2N1ezuw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "baseline-browser-mapping": "dist/cli.cjs" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/bcp-47": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/bcp-47/-/bcp-47-2.1.2.tgz", + "integrity": "sha512-wsv86UuNFuPnVieKLyECTT+CP1WSAHeoIg5P3xu2kA9Z+7fVPoKt7dxzSeEhtJel0AI+NW3fIW3KtTKQKUCngg==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/bcp-47-match": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/bcp-47-match/-/bcp-47-match-2.0.3.tgz", + "integrity": "sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/brace-expansion": { + "version": "5.0.13", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.13.tgz", + "integrity": "sha512-Vh3dmFbc4wZeox7M9I/0L9GfFd83Su4+yCck/OF9Gi/P/dAHn0RT7X4K9R7gMNMhDck3DvhR6QXsnQdjjgwNvQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^4.0.2" + }, + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/browserslist": { + "version": "4.29.6", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.29.6.tgz", + "integrity": "sha512-CmVVIQ3RVc5HxYEc9X84GvxK/C8C1wH8TlKAiO7uTxF8PDwt7r8t9Qk3J9NkMOVzX5O/HbLv3yzxZg9HPrnI9w==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "baseline-browser-mapping": "^2.11.37", + "caniuse-lite": "^1.0.30001826", + "electron-to-chromium": "^1.5.486", + "node-releases": "^2.0.64", + "update-browserslist-db": "^1.4.0" + }, + "bin": { + "browserslist": "cli.js" + }, + "engines": { + "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" + } + }, + "node_modules/cacheable": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/cacheable/-/cacheable-2.5.0.tgz", + "integrity": "sha512-60cyAOytib/OzBw1JNSoSV/boK1AtHryDIjvVBk7XbN4ugfkM3+Sry7fEjNgPMGgOjuaZPAp8ruZ0Cxafwyq9g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cacheable/memory": "^2.2.0", + "@cacheable/utils": "^2.5.0", + "hookified": "^1.15.0", + "keyv": "^5.6.0", + "qified": "^0.10.1" + } + }, + "node_modules/caniuse-lite": { + "version": "1.0.30001826", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001826.tgz", + "integrity": "sha512-wTB+9tIbLro/BCXwLuNV1meHE4L9dS6dArMDwgYfNBPMYScqClHyGunhkCSDtHhe/69Xl0sHlKgBVZ+fNsYtWA==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/caniuse-lite" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "CC-BY-4.0" + }, + "node_modules/chai": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/chai/-/chai-6.3.0.tgz", + "integrity": "sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/codemirror": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-6.0.2.tgz", + "integrity": "sha512-VhydHotNW5w1UGK0Qj96BwSk/Zqbp9WbnyK2W/eVMv4QyF41INRGpjUhFJY7/uDNuudSc33a/PKr4iDqRduvHw==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/commands": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/lint": "^6.0.0", + "@codemirror/search": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0" + } + }, + "node_modules/convert-source-map": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz", + "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==", + "dev": true, + "license": "MIT" + }, + "node_modules/crelt": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.7.tgz", + "integrity": "sha512-aK6BbWfhf4U/wCcLHKPJl/xa6VkVstRaPywWtMKGwuOLc/wZTyQYuoxgvZnNsBvv7Kg3YTBQYYBCggcviQczuA==", + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/csstype": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.4.tgz", + "integrity": "sha512-PoKaoPzQapnEoqUSnHx1u6W6ku8CVEgKsnpmmzU3m1nwkidpPBQ8V/Zq2+bWNrsOKoKLwTGdbx6xF7BXP1zLVQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/data-urls": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-8.0.0.tgz", + "integrity": "sha512-JQUCCK+/CAGbGGx618PlFZMXH81Jtj7t73CHv9dd/zVWvxgGT2zLFRjnKb+Ng46GIwcy+f7f88qd4duqllK+WQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "whatwg-mimetype": "^5.0.0", + "whatwg-url": "^17.1.2" + }, + "engines": { + "node": "^22.14.0 || >=24.0.0" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decimal.js": { + "version": "10.6.0", + "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz", + "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==", + "dev": true, + "license": "MIT" + }, + "node_modules/deep-is": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz", + "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/detect-libc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", + "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "node_modules/electron-to-chromium": { + "version": "1.5.488", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.488.tgz", + "integrity": "sha512-Uox8y5IeRGB/uXNMNSPfWaiI5/8d/2XG125oc+f2C5JniHcoMxsbCXcVFRZnIsdrgPwZQ6/k5SbSxhBirqQPuA==", + "dev": true, + "license": "ISC" + }, + "node_modules/enhanced-resolve": { + "version": "5.27.0", + "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.27.0.tgz", + "integrity": "sha512-Do6BB2xzlcc/odFg+XEYyneAx4T/WfywO71yw9ePS2tVfRsf7JVR4mUeELadIeHzixkzbG5DpluiEFPi2WGfYQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.4", + "tapable": "^2.3.3" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/entities": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-9.0.0.tgz", + "integrity": "sha512-oJFNDJg3kTPwAD1cNn2+WmUq4wFoo09npc3Ydf1D7ED4smRiWrsKnaLxykrTWgyGEcusc87P5dxlAleol9kpkg==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=20.19.0" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/es-module-lexer": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz", + "integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==", + "dev": true, + "license": "MIT" + }, + "node_modules/escalade": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint": { + "version": "10.15.0", + "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.15.0.tgz", + "integrity": "sha512-+5Wg4p+ze3sG1WErYgUO/3H1IQIfFBymVUA0Fo/XTeBOLS6UQIUekpSJ8sdRkn7O7wjh84b55w/roqavH2aScg==", + "dev": true, + "license": "MIT", + "workspaces": [ + "packages/*" + ], + "dependencies": { + "@eslint-community/eslint-utils": "^4.8.0", + "@eslint-community/regexpp": "^4.12.2", + "@eslint/config-array": "^0.23.6", + "@eslint/config-helpers": "^0.7.0", + "@eslint/core": "^1.2.1", + "@eslint/plugin-kit": "^0.7.3", + "@humanfs/node": "^0.16.8", + "@humanwhocodes/module-importer": "^1.0.1", + "@humanwhocodes/retry": "^0.4.2", + "@types/estree": "^1.0.6", + "ajv": "^6.14.0", + "cross-spawn": "^7.0.6", + "debug": "^4.3.2", + "escape-string-regexp": "^4.0.0", + "eslint-scope": "^9.1.2", + "eslint-visitor-keys": "^5.0.1", + "espree": "^11.2.0", + "esquery": "^1.7.0", + "esutils": "^2.0.2", + "fast-deep-equal": "^3.1.3", + "file-entry-cache": "11.1.5 || >11.1.6 <12", + "find-up": "^5.0.0", + "glob-parent": "^6.0.2", + "ignore": "^5.2.0", + "imurmurhash": "^0.1.4", + "is-glob": "^4.0.0", + "json-stable-stringify-without-jsonify": "^1.0.1", + "minimatch": "^11.0.5", + "natural-compare": "^1.4.0", + "optionator": "^0.9.3" + }, + "bin": { + "eslint": "bin/eslint.js" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://eslint.org/donate" + }, + "peerDependencies": { + "jiti": "*" + }, + "peerDependenciesMeta": { + "jiti": { + "optional": true + } + } + }, + "node_modules/eslint-config-prettier": { + "version": "10.1.8", + "resolved": "https://registry.npmjs.org/eslint-config-prettier/-/eslint-config-prettier-10.1.8.tgz", + "integrity": "sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==", + "dev": true, + "license": "MIT", + "bin": { + "eslint-config-prettier": "bin/cli.js" + }, + "funding": { + "url": "https://opencollective.com/eslint-config-prettier" + }, + "peerDependencies": { + "eslint": ">=7.0.0" + } + }, + "node_modules/eslint-plugin-react-hooks": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz", + "integrity": "sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/core": "^7.24.4", + "@babel/parser": "^7.24.4", + "hermes-parser": "^0.25.1", + "zod": "^3.25.0 || ^4.0.0", + "zod-validation-error": "^3.5.0 || ^4.0.0" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0" + } + }, + "node_modules/eslint-scope": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-9.1.2.tgz", + "integrity": "sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@types/esrecurse": "^4.3.1", + "@types/estree": "^1.0.8", + "esrecurse": "^4.3.0", + "estraverse": "^5.2.0" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-visitor-keys": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz", + "integrity": "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/espree": { + "version": "11.2.0", + "resolved": "https://registry.npmjs.org/espree/-/espree-11.2.0.tgz", + "integrity": "sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "acorn": "^8.16.0", + "acorn-jsx": "^5.3.2", + "eslint-visitor-keys": "^5.0.1" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/esquery": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.7.0.tgz", + "integrity": "sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "estraverse": "^5.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/esrecurse": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz", + "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "estraverse": "^5.2.0" + }, + "engines": { + "node": ">=4.0" + } + }, + "node_modules/estraverse": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", + "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=4.0" + } + }, + "node_modules/estree-walker": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz", + "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + } + }, + "node_modules/esutils": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/expect-type": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz", + "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-json-stable-stringify": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", + "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-levenshtein": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", + "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==", + "dev": true, + "license": "MIT" + }, + "node_modules/fdir": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", + "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.0.0" + }, + "peerDependencies": { + "picomatch": "^3 || ^4" + }, + "peerDependenciesMeta": { + "picomatch": { + "optional": true + } + } + }, + "node_modules/file-entry-cache": { + "version": "11.1.5", + "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-11.1.5.tgz", + "integrity": "sha512-+PFTHITI08JIGhnNpGNI8T8inUpgZfk3GNEqfT9R2zZV2iFXg3CvqzSl/uEhs7TSGujYRELEANyDvS8Fj7+S7Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "flat-cache": "^6.1.23" + } + }, + "node_modules/find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "license": "MIT", + "dependencies": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/flat-cache": { + "version": "6.1.23", + "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-6.1.23.tgz", + "integrity": "sha512-f++BY9pTk+983xK1FLzlLpmM0i0z+jHmx3QESGkURMXujQZz1k5wzwX6hjnQ8goaD0B+sYnDK1yZ6MTyZfUaqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "cacheable": "^2.5.0", + "flatted": "^3.4.2", + "hookified": "^1.15.0" + } + }, + "node_modules/flatted": { + "version": "3.4.4", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.4.tgz", + "integrity": "sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q==", + "dev": true, + "license": "ISC" + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/gensync": { + "version": "1.0.0-beta.2", + "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz", + "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/glob-parent": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz", + "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==", + "dev": true, + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.3" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.12", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.12.tgz", + "integrity": "sha512-iuyGF2E4oafQfPsRrG2wtY2ILupMhvtdrhzrxB+0VcjsPpSPttpfYdjnGFGsTi5MaJFjI1jOKHPQ6UTbTj9TAw==", + "dev": true, + "license": "BlueOak-1.0.0" + }, + "node_modules/hashery": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/hashery/-/hashery-1.5.1.tgz", + "integrity": "sha512-iZyKG96/JwPz1N55vj2Ie2vXbhu440zfUfJvSwEqEbeLluk7NnapfGqa7LH0mOsnDxTF85Mx8/dyR6HfqcbmbQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "hookified": "^1.15.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/hermes-estree": { + "version": "0.25.1", + "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.25.1.tgz", + "integrity": "sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==", + "dev": true, + "license": "MIT" + }, + "node_modules/hermes-parser": { + "version": "0.25.1", + "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.25.1.tgz", + "integrity": "sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "hermes-estree": "0.25.1" + } + }, + "node_modules/hookified": { + "version": "1.15.1", + "resolved": "https://registry.npmjs.org/hookified/-/hookified-1.15.1.tgz", + "integrity": "sha512-MvG/clsADq1GPM2KGo2nyfaWVyn9naPiXrqIe4jYjXNZQt238kWyOGrsyc/DmRAQ+Re6yeo6yX/yoNCG5KAEVg==", + "dev": true, + "license": "MIT" + }, + "node_modules/html-encoding-sniffer": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-7.0.0.tgz", + "integrity": "sha512-UikN5yr7xsCDAq87Or5or0PAlD3HJJOKVzM05az588WnpDJ4Ux7a2A53Qi6gofGg2/EtvF/H4hCi/TXfCW4Y6w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@exodus/bytes": "^1.15.1" + }, + "engines": { + "node": "^22.13.0 || >=24.0.0" + } + }, + "node_modules/ignore": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz", + "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/imurmurhash": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", + "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.8.19" + } + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-potential-custom-element-name": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz", + "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, + "license": "ISC" + }, + "node_modules/jiti": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz", + "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==", + "dev": true, + "license": "MIT", + "bin": { + "jiti": "lib/jiti-cli.mjs" + } + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/jsdom": { + "version": "31.0.1", + "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-31.0.1.tgz", + "integrity": "sha512-CbhJL8ZQg3eKswxSZth4QO9tW0jPIhmR0vtSXQSbKSfWbwIT6hoRc17wdHIVTQ43KI0mdV5iTJr3281IDgVZ5g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@exodus/bytes": "^1.16.0", + "bcp-47": "^2.1.2", + "bcp-47-match": "^2.0.3", + "data-urls": "^8.0.0", + "decimal.js": "^10.6.0", + "html-encoding-sniffer": "^7.0.0", + "is-potential-custom-element-name": "^1.0.1", + "lru-cache": "^11.5.3", + "parse5": "^8.1.0", + "parse5-parser-stream": "^8.1.0", + "saxes": "^6.0.0", + "tough-cookie": "^6.0.2", + "undici": "^8.12.3", + "w3c-xmlserializer": "^6.0.0", + "webidl-conversions": "^8.0.1", + "whatwg-mimetype": "^5.0.0", + "whatwg-url": "^17.3.0", + "xml-name-validator": "^5.0.0" + }, + "engines": { + "node": "^22.22.2 || ^24.15.0 || >=26.0.0" + }, + "peerDependencies": { + "@napi-rs/canvas": "^1.0.13" + }, + "peerDependenciesMeta": { + "@napi-rs/canvas": { + "optional": true + } + } + }, + "node_modules/jsdom/node_modules/lru-cache": { + "version": "11.5.3", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz", + "integrity": "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==", + "dev": true, + "license": "BlueOak-1.0.0", + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/jsesc": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz", + "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==", + "dev": true, + "license": "MIT", + "bin": { + "jsesc": "bin/jsesc" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true, + "license": "MIT" + }, + "node_modules/json-stable-stringify-without-jsonify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", + "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==", + "dev": true, + "license": "MIT" + }, + "node_modules/json5": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", + "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", + "dev": true, + "license": "MIT", + "bin": { + "json5": "lib/cli.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/keyv": { + "version": "5.6.0", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-5.6.0.tgz", + "integrity": "sha512-CYDD3SOtsHtyXeEORYRx2qBtpDJFjRTGXUtmNEMGyzYOKj1TE3tycdlho7kA1Ufx9OYWZzg52QFBGALTirzDSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@keyv/serialize": "^1.1.1" + } + }, + "node_modules/levn": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz", + "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "prelude-ls": "^1.2.1", + "type-check": "~0.4.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/lightningcss": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz", + "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==", + "dev": true, + "license": "MPL-2.0", + "dependencies": { + "detect-libc": "^2.0.3" + }, + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + }, + "optionalDependencies": { + "lightningcss-android-arm64": "1.33.0", + "lightningcss-darwin-arm64": "1.33.0", + "lightningcss-darwin-x64": "1.33.0", + "lightningcss-freebsd-x64": "1.33.0", + "lightningcss-linux-arm-gnueabihf": "1.33.0", + "lightningcss-linux-arm64-gnu": "1.33.0", + "lightningcss-linux-arm64-musl": "1.33.0", + "lightningcss-linux-x64-gnu": "1.33.0", + "lightningcss-linux-x64-musl": "1.33.0", + "lightningcss-win32-arm64-msvc": "1.33.0", + "lightningcss-win32-x64-msvc": "1.33.0" + } + }, + "node_modules/lightningcss-android-arm64": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.33.0.tgz", + "integrity": "sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-darwin-arm64": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.33.0.tgz", + "integrity": "sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-darwin-x64": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.33.0.tgz", + "integrity": "sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-freebsd-x64": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.33.0.tgz", + "integrity": "sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-linux-arm-gnueabihf": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.33.0.tgz", + "integrity": "sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-linux-arm64-gnu": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.33.0.tgz", + "integrity": "sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MPL-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-linux-arm64-musl": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.33.0.tgz", + "integrity": "sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MPL-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-linux-x64-gnu": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.33.0.tgz", + "integrity": "sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MPL-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-linux-x64-musl": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.33.0.tgz", + "integrity": "sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MPL-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-win32-arm64-msvc": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.33.0.tgz", + "integrity": "sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss-win32-x64-msvc": { + "version": "1.33.0", + "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.33.0.tgz", + "integrity": "sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MPL-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 12.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-locate": "^5.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "license": "ISC", + "dependencies": { + "yallist": "^3.0.2" + } + }, + "node_modules/magic-string": { + "version": "1.4.5", + "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.5.tgz", + "integrity": "sha512-oLLC2+YvQUfAa+vxoufE/yc1icb87M9iXIRqAoR/2EhE/8cb3SF/+Gi0c2By1B+5Vz2e2vQtUvHiu1+63Znh+w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.6.0" + } + }, + "node_modules/minimatch": { + "version": "11.0.9", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-11.0.9.tgz", + "integrity": "sha512-KCFkfyjqerNlSstjlhIGNXIKZGA/6O4V4RlhZ+Dsr621SPPw0mzlypE9D9ZOoPiVefHID+j7/XuMMlqfD/F60Q==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/nonrecursive-glob-match": "^1.1.0", + "brace-expansion": "^5.0.12" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/nanoid": { + "version": "3.3.20", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.20.tgz", + "integrity": "sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/natural-compare": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz", + "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==", + "dev": true, + "license": "MIT" + }, + "node_modules/node-releases": { + "version": "2.0.65", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.65.tgz", + "integrity": "sha512-PfvofsGQ+MiOQIPkX9fU8ELUWmy5zL74CdQaph/ismKszfFkfwXaw0cGiwbwym2hT9k5+mdyl8O5WQ1MD8EHmA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/obug": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/obug/-/obug-3.0.0.tgz", + "integrity": "sha512-5vvB5+W7ePv+p3uqxi+RcW1XAzLW0/hxt3/4X4Lc4qHudzOhmBiBwOY6DRob4WnanAEGvNcLjF+KNOufrUoEQw==", + "dev": true, + "funding": [ + "https://github.com/sponsors/sxzz", + "https://opencollective.com/debug" + ], + "license": "MIT", + "engines": { + "node": ">=12.20.0" + } + }, + "node_modules/optionator": { + "version": "0.9.4", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz", + "integrity": "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==", + "dev": true, + "license": "MIT", + "dependencies": { + "deep-is": "^0.1.3", + "fast-levenshtein": "^2.0.6", + "levn": "^0.4.1", + "prelude-ls": "^1.2.1", + "type-check": "^0.4.0", + "word-wrap": "^1.2.5" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/p-limit": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", + "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "yocto-queue": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-limit": "^3.0.2" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/parse5": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.1.1.tgz", + "integrity": "sha512-EcR/6WDcU7b2N3vQSxKALCk9lXGtUMQxXio008OEMBE0kavu/7JLfBEeFPzi43nMqVDSbEn3QCK+BMCc9zO//w==", + "dev": true, + "license": "MIT", + "dependencies": { + "entities": "^9.0.0" + }, + "funding": { + "url": "https://github.com/inikulin/parse5?sponsor=1" + } + }, + "node_modules/parse5-parser-stream": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/parse5-parser-stream/-/parse5-parser-stream-8.1.1.tgz", + "integrity": "sha512-hMcVbbUJcQmP8rURWUdYrT1flRiBiBVjq/RYGguJpDUgIXSqdYKlE0CxthmdMWoSlBAuL5bUBa73g0pttSy7Hw==", + "dev": true, + "license": "MIT", + "dependencies": { + "parse5": "^8.1.1" + }, + "funding": { + "url": "https://github.com/inikulin/parse5?sponsor=1" + } + }, + "node_modules/path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "dev": true, + "license": "ISC" + }, + "node_modules/picomatch": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz", + "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/postcss": { + "version": "8.5.33", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.33.tgz", + "integrity": "sha512-RVHEU9/Pp1Fnjr/MpAJsZoADukCKhfIi15OunEYiGktIkYLkPVvC1sioWolGDS7XByMTx9m/IGbro0Js13zhnQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.20", + "picocolors": "^1.1.1", + "source-map-js": "^1.2.2" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/prelude-ls": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", + "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/prettier": { + "version": "3.10.1", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.10.1.tgz", + "integrity": "sha512-70vp3ZUYoPlFbF9uiTdXHUUCGEIp7d4+6p+8DYbkm2jP7x/3i/paXVF6dopSI3zd/CEitrZN1rc4i85xWmmXlg==", + "dev": true, + "license": "MIT", + "bin": { + "prettier": "bin/prettier.cjs" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/punycode": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz", + "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/qified": { + "version": "0.10.1", + "resolved": "https://registry.npmjs.org/qified/-/qified-0.10.1.tgz", + "integrity": "sha512-+Owyggi9IxT1ePKGafcI87ubSmxol6smwJ+RAHDQlx9+9cPwFWDiKFFCPuWhr9ignlGpZ9vDQLw67N4dcTVFEA==", + "dev": true, + "license": "MIT", + "dependencies": { + "hookified": "^2.1.1" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/qified/node_modules/hookified": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/hookified/-/hookified-2.2.0.tgz", + "integrity": "sha512-p/LgFzRN5FeoD3DLS6bkUapeye6E4SI6yJs6KetENd18S+FBthqYq2amJUWpt5z0EQwwHemidjY5OqJGEKm5uA==", + "dev": true, + "license": "MIT" + }, + "node_modules/react": { + "version": "19.3.1", + "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz", + "integrity": "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-dom": { + "version": "19.3.1", + "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.1.tgz", + "integrity": "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ==", + "license": "MIT", + "dependencies": { + "scheduler": "^0.28.0" + }, + "peerDependencies": { + "react": "^19.3.1" + } + }, + "node_modules/rolldown": { + "version": "1.2.19", + "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.19.tgz", + "integrity": "sha512-QIiV1J9d0pzN4jeeTH4sjPy0AZ6cAy2cG0ExeoE1+U8Rvj+hR3gYkokx0YbeUNGlZqiQJJ2utcETe0oKXwzsuA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@oxc-project/types": "=0.156.0", + "@rolldown/pluginutils": "^1.0.0" + }, + "bin": { + "rolldown": "bin/cli.mjs" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "optionalDependencies": { + "@rolldown/binding-android-arm-eabi": "1.2.19", + "@rolldown/binding-android-arm64": "1.2.19", + "@rolldown/binding-darwin-arm64": "1.2.19", + "@rolldown/binding-darwin-x64": "1.2.19", + "@rolldown/binding-freebsd-x64": "1.2.19", + "@rolldown/binding-linux-arm-gnueabihf": "1.2.19", + "@rolldown/binding-linux-arm64-gnu": "1.2.19", + "@rolldown/binding-linux-arm64-musl": "1.2.19", + "@rolldown/binding-linux-ppc64-gnu": "1.2.19", + "@rolldown/binding-linux-s390x-gnu": "1.2.19", + "@rolldown/binding-linux-x64-gnu": "1.2.19", + "@rolldown/binding-linux-x64-musl": "1.2.19", + "@rolldown/binding-openharmony-arm64": "1.2.19", + "@rolldown/binding-wasm32-wasi": "1.2.19", + "@rolldown/binding-win32-arm64-msvc": "1.2.19", + "@rolldown/binding-win32-x64-msvc": "1.2.19" + } + }, + "node_modules/saxes": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz", + "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==", + "dev": true, + "license": "ISC", + "dependencies": { + "xmlchars": "^2.2.0" + }, + "engines": { + "node": ">=v12.22.7" + } + }, + "node_modules/scheduler": { + "version": "0.28.0", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz", + "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==", + "license": "MIT" + }, + "node_modules/semver": { + "version": "6.3.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.2.tgz", + "integrity": "sha512-GYrCADwpu6yV5OAvchkQ27Z5wwMxWAEMg5NNWjyHh/5DboFFqbdbvYNIvZouQpxXyeMPoTOh0vdPYKlf0ZswdQ==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/source-map-js": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz", + "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/std-env": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.3.0.tgz", + "integrity": "sha512-OtU/EgQ1kIm5KwqQpBC6ZEMXrZRui11w8zgfTWp8cdO9B8OaPsbA8bTHO2P+HNo1VlUTGMVBwPhydu6poeXiag==", + "dev": true, + "license": "MIT" + }, + "node_modules/style-mod": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.5.tgz", + "integrity": "sha512-WQ2llCZa9sZSkJA+aOwpg5DkfbAXFKGh//t3MRTBeruFiSBC+GXUmbBzrw3bXyboCWAbtCW9InDfBsXrRD/rAg==", + "license": "MIT" + }, + "node_modules/tailwindcss": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.5.tgz", + "integrity": "sha512-FcQk9BuffmEHJP2G0XmB2SplU1aLTI7j07Kunk+U74Ny+XiWOtzXz9aujFZ/avntw1e2cOv/3PkgzflQ7gX2vQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/tapable": { + "version": "2.3.4", + "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.3.4.tgz", + "integrity": "sha512-NHFiWnAbMJxNNpBwiO7jJVGDuqMxT9/oV8v57RR+fgBQShkJil5inGD8/xWy0hjLyHQyX1tu27QANhlz3KBqCg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/webpack" + } + }, + "node_modules/tinybench": { + "version": "6.2.3", + "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-6.2.3.tgz", + "integrity": "sha512-Al01C2JIBnO2CXCAPbpAl6sUiOZHeThGtHYNTa51JRw9PyWOCdr+9Ong05R4qg/Sk3+H645E8ov1h2c58ityNw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/tinyexec": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz", + "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/tinyglobby": { + "version": "0.2.17", + "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz", + "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fdir": "^6.5.0", + "picomatch": "^4.0.4" + }, + "engines": { + "node": ">=12.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/SuperchupuDev" + } + }, + "node_modules/tldts": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.5.4.tgz", + "integrity": "sha512-Rn2ABgjHZrA+jzqom5zhxA0hLohzYrIgfCPyhpTUxqsUrcsBYuab49LseR9waB9Jr8/MxdodvMHA91oRiGLO3Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "tldts-core": "^7.5.4" + }, + "bin": { + "tldts": "bin/cli.js" + } + }, + "node_modules/tldts-core": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.5.4.tgz", + "integrity": "sha512-9+4zWtKEDZ3V3FoZ1B97rv+5z5oqp7yeXGVze3CxgQ+CJro9do9DCPD00wxstYZDXDMXsurkBerFfiB6GYtPbA==", + "dev": true, + "license": "MIT" + }, + "node_modules/tough-cookie": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.1.0.tgz", + "integrity": "sha512-FTxc8u8Kl2tz0Lat1u8ksvcy8bwHRyEMawwTWybo51JqaC6O7SvfuhAKg+Ld6VqyIe2QRJBzY9HA7y2WyFRT2w==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "tldts": "^7.0.5" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/tr46": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-7.0.0.tgz", + "integrity": "sha512-BcDSDW+SIGWVOns1Zm6Yg91q9AEj7eaID0QDY9oIqJD1A8dscNwMcl9Sms2DeuWCNov1X0/oXanHGYQBSLwZsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "punycode": "^2.3.1" + }, + "engines": { + "node": "^22.14.0 || >=24.0.0" + } + }, + "node_modules/ts-api-utils": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz", + "integrity": "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18.12" + }, + "peerDependencies": { + "typescript": ">=4.8.4" + } + }, + "node_modules/tslib": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz", + "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==", + "dev": true, + "license": "0BSD", + "optional": true + }, + "node_modules/type-check": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", + "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==", + "dev": true, + "license": "MIT", + "dependencies": { + "prelude-ls": "^1.2.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/typescript": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", + "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/typescript-eslint": { + "version": "8.73.0", + "resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.73.0.tgz", + "integrity": "sha512-+EnKy9rkYPun4l+kG2bDuYWQ6y1tGVgdR/tY1U9AC6h21CjEwOoc7gsjwe0FXB8uWFzk4QiCFbuRWgX758PiAg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/eslint-plugin": "8.73.0", + "@typescript-eslint/parser": "8.73.0", + "@typescript-eslint/typescript-estree": "8.73.0", + "@typescript-eslint/utils": "8.73.0" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", + "typescript": ">=4.8.4 <6.1.0" + } + }, + "node_modules/undici": { + "version": "8.12.4", + "resolved": "https://registry.npmjs.org/undici/-/undici-8.12.4.tgz", + "integrity": "sha512-8Mx+uNKKER2bA4AdtedkqRbwUCIJFr2nJckXRe5yrDqzePqwLP7VNcctN8/XdmDSbF7mS+jJKIszlL+vbam1VA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/undici-types": { + "version": "7.24.6", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz", + "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==", + "dev": true, + "license": "MIT" + }, + "node_modules/update-browserslist-db": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.4.0.tgz", + "integrity": "sha512-WPJuOnjI9FWDct4fB+ej4Mz8opLaw5CDcZ2t44tFZ0vIQVYWzBhWR3mkixuUj/A7+vY4V9+ApOZ2YYLwdgq46w==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "escalade": "^3.2.0", + "picocolors": "^1.1.1" + }, + "bin": { + "update-browserslist-db": "cli.js" + }, + "peerDependencies": { + "browserslist": ">= 4.21.0" + } + }, + "node_modules/uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "punycode": "^2.1.0" + } + }, + "node_modules/use-sync-external-store": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.7.0.tgz", + "integrity": "sha512-6L+EeigHMQhdaIPNIFUKwfWJSwWFQ8gJbJ2DLOs5sDIegTwR9fRxvnM3uciHKjIZhFz+KAv2emhWMRvDmMcY8A==", + "license": "MIT", + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/vite": { + "version": "8.3.8", + "resolved": "https://registry.npmjs.org/vite/-/vite-8.3.8.tgz", + "integrity": "sha512-LzOn3h9rG/0vhLdXrV4yJ4QFA9eEoqCl+Yx+kGJd7aB9w6nfNgVHKSYwLPZUHrz4ZGa+t+kXjV9itvcHDLQouA==", + "dev": true, + "license": "MIT", + "dependencies": { + "lightningcss": "^1.33.0", + "picomatch": "^4.0.7", + "postcss": "^8.5.32", + "rolldown": "~1.2.18", + "tinyglobby": "^0.2.17" + }, + "bin": { + "vite": "bin/vite.js" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "funding": { + "url": "https://github.com/vitejs/vite?sponsor=1" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + }, + "peerDependencies": { + "@types/node": "^20.19.0 || >=22.12.0", + "@vitejs/devtools": "^0.7.1 || ^0.8.0", + "esbuild": "^0.27.0 || ^0.28.0", + "jiti": ">=1.21.0", + "less": "^4.0.0", + "sass": "^1.70.0", + "sass-embedded": "^1.70.0", + "stylus": ">=0.54.8", + "sugarss": "^5.0.0", + "terser": "^5.16.0", + "tsx": "^4.8.1", + "yaml": "^2.4.2" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + }, + "@vitejs/devtools": { + "optional": true + }, + "esbuild": { + "optional": true + }, + "jiti": { + "optional": true + }, + "less": { + "optional": true + }, + "sass": { + "optional": true + }, + "sass-embedded": { + "optional": true + }, + "stylus": { + "optional": true + }, + "sugarss": { + "optional": true + }, + "terser": { + "optional": true + }, + "tsx": { + "optional": true + }, + "yaml": { + "optional": true + } + } + }, + "node_modules/vitest": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/vitest/-/vitest-5.1.0.tgz", + "integrity": "sha512-MzmNFnrwa8v8lF1bLxw3UJ4EREwVOVb75VqJZmUDRjJ6EluK/x9th7qTbaeDk41WxE1GxWqmTXcdsfobfH5sOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/chai": "^5.2.2", + "@vitest/mocker": "5.1.0", + "chai": "^6.3.0", + "es-module-lexer": "^2.3.2", + "expect-type": "^1.4.0", + "magic-string": "^1.4.3", + "obug": "^3.0.0", + "picomatch": "^4.0.7", + "std-env": "^4.3.0", + "tinybench": "^6.2.2", + "tinyexec": "^1.3.1", + "tinyglobby": "^0.2.17", + "why-is-node-running": "3.2.1" + }, + "bin": { + "vitest": "vitest.mjs" + }, + "engines": { + "node": "^22.12.0 || ^24.0.0 || >=26.0.0" + }, + "funding": { + "url": "https://opencollective.com/vitest" + }, + "peerDependencies": { + "@edge-runtime/vm": "*", + "@opentelemetry/api": "^1.9.0", + "@types/node": "^22.0.0 || >=24.0.0", + "@vitest/browser-playwright": "5.1.0", + "@vitest/browser-preview": "5.1.0", + "@vitest/browser-webdriverio": "^5.0.0-beta.5 || >=5.0.0", + "@vitest/coverage-istanbul": "5.1.0", + "@vitest/coverage-v8": "5.1.0", + "@vitest/ui": "5.1.0", + "happy-dom": "*", + "jsdom": "*", + "vite": "^6.4.0 || ^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "@edge-runtime/vm": { + "optional": true + }, + "@opentelemetry/api": { + "optional": true + }, + "@types/node": { + "optional": true + }, + "@vitest/browser-playwright": { + "optional": true + }, + "@vitest/browser-preview": { + "optional": true + }, + "@vitest/browser-webdriverio": { + "optional": true + }, + "@vitest/coverage-istanbul": { + "optional": true + }, + "@vitest/coverage-v8": { + "optional": true + }, + "@vitest/ui": { + "optional": true + }, + "happy-dom": { + "optional": true + }, + "jsdom": { + "optional": true + }, + "vite": { + "optional": false + } + } + }, + "node_modules/w3c-keyname": { + "version": "2.2.8", + "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz", + "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==", + "license": "MIT" + }, + "node_modules/w3c-xmlserializer": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-6.0.0.tgz", + "integrity": "sha512-4Nsy8K5Tr6SPDH9jhKJOHf7ChDrc1zufZTVSF7x72hwuEXBqxqk9G6cK+K2NRUtB3iELRJqjXb4JPDMBjMTl2Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "xml-name-validator": "^5.0.0" + }, + "engines": { + "node": "^22.22.2 || ^24.15.0 || >=26.0.0" + } + }, + "node_modules/webidl-conversions": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz", + "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=20" + } + }, + "node_modules/whatwg-mimetype": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz", + "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20" + } + }, + "node_modules/whatwg-url": { + "version": "17.3.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-17.3.0.tgz", + "integrity": "sha512-KwOAJrpf+GTgBvcBQJcP38sMF0DsQKdwtG+TxM2pW44P6E5k0hDbWrDmyuJDIF0Uef0aQq0ZoJs+5oI+k8ddhg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@exodus/bytes": "^1.16.0", + "tr46": "^7.0.0", + "webidl-conversions": "^8.0.1" + }, + "engines": { + "node": "^22.14.0 || >=24.0.0" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/why-is-node-running": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-3.2.1.tgz", + "integrity": "sha512-Tb2FUhB4vUsGQlfSquQLYkApkuPAFQXGFzxWKHHumVz2dK+X1RUm/HnID4+TfIGYJ1kTcwOaCk/buYCEJr6YjQ==", + "dev": true, + "license": "MIT", + "bin": { + "why-is-node-running": "cli.js" + }, + "engines": { + "node": ">=20.11" + } + }, + "node_modules/word-wrap": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz", + "integrity": "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/xml-name-validator": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz", + "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=18" + } + }, + "node_modules/xmlchars": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz", + "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==", + "dev": true, + "license": "MIT" + }, + "node_modules/yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "dev": true, + "license": "ISC" + }, + "node_modules/yocto-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", + "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/zod": { + "version": "4.6.7", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz", + "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zod-validation-error": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/zod-validation-error/-/zod-validation-error-4.0.2.tgz", + "integrity": "sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18.0.0" + }, + "peerDependencies": { + "zod": "^3.25.0 || ^4.0.0" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..219dfdc --- /dev/null +++ b/package.json @@ -0,0 +1,52 @@ +{ + "name": "stackql-workbench", + "private": true, + "version": "0.1.0", + "description": "Desktop query IDE and chat interface for StackQL", + "license": "MIT", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc -b && vite build", + "preview": "vite preview", + "tauri": "tauri", + "lint": "eslint . && prettier --check .", + "format": "prettier --write .", + "typecheck": "tsc -b", + "test": "node scripts/test.js" + }, + "dependencies": { + "@codemirror/autocomplete": "^6.20.4", + "@codemirror/commands": "^6.11.1", + "@codemirror/lang-sql": "^6.10.0", + "@codemirror/language": "^6.13.1", + "@codemirror/state": "^6.7.6", + "@codemirror/view": "^6.43.15", + "@lezer/highlight": "^1.2.5", + "@tanstack/react-table": "^9.3.1", + "@tanstack/react-virtual": "^3.14.26", + "@tauri-apps/api": "^2.12.5", + "codemirror": "^6.0.2", + "react": "^19.3.1", + "react-dom": "^19.3.1" + }, + "devDependencies": { + "@eslint/js": "^10.0.1", + "@tailwindcss/vite": "^4.3.5", + "@tauri-apps/cli": "^2.12.5", + "@types/node": "^24.19.2", + "@types/react": "^19.3.0", + "@types/react-dom": "^19.3.0", + "@vitejs/plugin-react": "^6.3.0", + "eslint": "^10.15.0", + "eslint-config-prettier": "^10.1.8", + "eslint-plugin-react-hooks": "^7.1.1", + "jsdom": "^31.0.1", + "prettier": "^3.10.1", + "tailwindcss": "^4.3.5", + "typescript": "~6.0.3", + "typescript-eslint": "^8.73.0", + "vite": "^8.3.8", + "vitest": "^5.1.0" + } +} diff --git a/scripts/check-exe-imports.js b/scripts/check-exe-imports.js new file mode 100644 index 0000000..2559d19 --- /dev/null +++ b/scripts/check-exe-imports.js @@ -0,0 +1,193 @@ +// Lists the libraries a Windows executable asks the system for, and fails +// when one of them is a runtime the executable should carry inside it. +// +// node scripts/check-exe-imports.js [x64 | arm64] +// +// With a processor named, it also fails when the executable is built for +// another one. The MSI comes for x64 and for arm64, and a build on the wrong +// toolchain would otherwise pass for the right one. +// +// The executable is shipped on its own, beside stackql.exe. It must not need +// a C runtime, or any other library, that has to be installed or copied next +// to it. That includes the Universal C runtime: Windows 10 and later have +// it, but it is a runtime all the same, and the build links it in. This +// reads the import tables of the file, both the ordinary one and the one for +// libraries loaded on first use, so it reports what the loader will really +// be asked for and not what happens to be spelled in the file. +// +// The page renderer, WebView2, is not found this way. The executable does +// not link to it: it finds a runtime when it starts. See README.md, "What the +// installers take". + +import fs from 'node:fs'; +import process from 'node:process'; + +/** + * Libraries the executable must not lean on: the C runtime in its several + * forms, and the WebView2 loader. Everything else it imports is Windows. + */ +const RUNTIME_LIBRARIES = [ + /^api-ms-win-crt-/i, + /^ucrtbase/i, + /^vcruntime/i, + /^msvcp/i, + /^msvcr/i, + /^vcomp/i, + /^concrt/i, + /^webview2loader/i, +]; + +/** The processors a PE file can name, by the names the builds go by. */ +const PROCESSORS = new Map([ + [0x8664, 'x64'], + [0xaa64, 'arm64'], + [0x014c, 'x86'], +]); + +/** + * The processor a PE file is built for. + * + * @param {Buffer} file The whole executable. + * @returns {string} + */ +export function builtFor(file) { + const pe = file.readUInt32LE(0x3c); + if (file.toString('latin1', pe, pe + 4) !== 'PE\0\0') { + throw new Error('Not a Windows executable.'); + } + const machine = file.readUInt16LE(pe + 4); + return PROCESSORS.get(machine) ?? `machine 0x${machine.toString(16)}`; +} + +/** + * The names in the import tables of a PE file, in the order they appear. + * + * @param {Buffer} file The whole executable. + * @returns {string[]} + */ +export function importedLibraries(file) { + const pe = file.readUInt32LE(0x3c); + if (file.toString('latin1', pe, pe + 4) !== 'PE\0\0') { + throw new Error('Not a Windows executable.'); + } + const coff = pe + 4; + const sectionCount = file.readUInt16LE(coff + 2); + const optional = coff + 20; + const optionalSize = file.readUInt16LE(coff + 16); + const magic = file.readUInt16LE(optional); + // Where the table of directories starts depends on whether it is 64-bit. + const directories = optional + (magic === 0x20b ? 112 : 96); + + /** @type {{ virtualSize: number, virtualAddress: number, rawSize: number, rawOffset: number }[]} */ + const sections = []; + for (let index = 0; index < sectionCount; index += 1) { + const at = optional + optionalSize + index * 40; + sections.push({ + virtualSize: file.readUInt32LE(at + 8), + virtualAddress: file.readUInt32LE(at + 12), + rawSize: file.readUInt32LE(at + 16), + rawOffset: file.readUInt32LE(at + 20), + }); + } + + /** + * Where an address in the loaded image is in the file. + * + * @param {number} rva + * @returns {number | null} + */ + const offsetOf = (rva) => { + for (const section of sections) { + const size = Math.max(section.virtualSize, section.rawSize); + if (rva >= section.virtualAddress && rva < section.virtualAddress + size) { + return rva - section.virtualAddress + section.rawOffset; + } + } + return null; + }; + + /** + * The text that starts at an address and runs to the next zero byte. + * + * @param {number} rva + * @returns {string | null} + */ + const textAt = (rva) => { + const start = offsetOf(rva); + if (start === null) { + return null; + } + let end = start; + while (end < file.length && file[end] !== 0) { + end += 1; + } + return file.toString('latin1', start, end); + }; + + /** @type {string[]} */ + const names = []; + // The second directory is the import table and the fourteenth the table + // of libraries loaded on first use. Each is a list of entries of a fixed + // size, ended by an empty one, with the library's name at a known place. + const tables = [ + { directory: 1, entrySize: 20, nameAt: 12 }, + { directory: 13, entrySize: 32, nameAt: 4 }, + ]; + for (const table of tables) { + const rva = file.readUInt32LE(directories + table.directory * 8); + const start = rva === 0 ? null : offsetOf(rva); + if (start === null) { + continue; + } + for (let at = start; at + table.entrySize <= file.length; at += table.entrySize) { + const nameRva = file.readUInt32LE(at + table.nameAt); + if (nameRva === 0) { + break; + } + const name = textAt(nameRva); + if (name) { + names.push(name); + } + } + } + return names; +} + +/** + * The imported libraries that are a runtime and not Windows itself. + * + * @param {string[]} names + * @returns {string[]} + */ +export function runtimeLibraries(names) { + return names.filter((name) => RUNTIME_LIBRARIES.some((pattern) => pattern.test(name))); +} + +/** + * @param {string[]} items + * @returns {string} + */ +const list = (items) => `${items.map((name) => ` ${name}`).join('\n')}\n`; + +const target = process.argv[2]; +const expected = process.argv[3]; +if (target) { + const file = fs.readFileSync(target); + const processor = builtFor(file); + process.stdout.write(`${target} is built for ${processor}.\n`); + if (expected && expected !== processor) { + process.stderr.write(`It should be built for ${expected}.\n`); + process.exit(1); + } + const names = importedLibraries(file); + const sorted = [...new Set(names.map((name) => name.toLowerCase()))].sort(); + process.stdout.write(`${target} asks the system for ${sorted.length} libraries:\n`); + process.stdout.write(list(sorted)); + const runtime = runtimeLibraries(sorted); + if (runtime.length > 0) { + process.stderr.write('\nThese are a runtime the executable should carry inside it:\n'); + process.stderr.write(list(runtime)); + process.exit(1); + } + process.stdout.write('\nNone of them is a runtime. All are Windows itself.\n'); +} diff --git a/scripts/test.js b/scripts/test.js new file mode 100644 index 0000000..be415ef --- /dev/null +++ b/scripts/test.js @@ -0,0 +1,31 @@ +// Runs the webview tests. +// +// On Windows, Vitest loads its own modules twice when the working directory +// is spelled with a lower-case drive letter, which an editor's terminal can +// do. Every suite then fails before running a single test with "Cannot read +// properties of undefined (reading 'config')". This launcher starts Vitest +// from the same directory spelled with an upper-case drive letter. + +import { spawnSync } from 'node:child_process'; +import { createRequire } from 'node:module'; +import path from 'node:path'; +import process from 'node:process'; + +let cwd = process.cwd(); +if (process.platform === 'win32' && /^[a-z]:/.test(cwd)) { + cwd = cwd.charAt(0).toUpperCase() + cwd.slice(1); +} + +const require = createRequire(path.join(cwd, 'package.json')); +const vitest = path.join(path.dirname(require.resolve('vitest/package.json')), 'vitest.mjs'); + +const result = spawnSync(process.execPath, [vitest, 'run', ...process.argv.slice(2)], { + cwd, + stdio: 'inherit', +}); + +if (result.error) { + process.stderr.write(result.error.message + '\n'); + process.exit(1); +} +process.exit(result.status ?? 1); diff --git a/src-tauri/.cargo/config.toml b/src-tauri/.cargo/config.toml new file mode 100644 index 0000000..b1e22c0 --- /dev/null +++ b/src-tauri/.cargo/config.toml @@ -0,0 +1,11 @@ +# The Windows executable is shipped on its own, beside stackql.exe, so it +# carries the whole C runtime inside it: the start-up code, the Visual C++ +# runtime and the Universal C runtime. What it then asks of the system is +# Windows itself and nothing that has to be installed. +# +# Tauri's own default links the first two in and leaves the Universal C +# runtime to Windows. That default is switched off in tauri.conf.json, under +# build > windows > staticVCRuntime, because it would undo this flag for the +# Universal C runtime. Keep the two settings together. +[target.'cfg(all(windows, target_env = "msvc"))'] +rustflags = ["-C", "target-feature=+crt-static"] diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock new file mode 100644 index 0000000..76cfbd4 --- /dev/null +++ b/src-tauri/Cargo.lock @@ -0,0 +1,5906 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "alloc-no-stdlib" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2fb6cfd47bf496ff64095c20eaba0c201404ee38714d4142fcfa1dc334fcc7a" + +[[package]] +name = "alloc-stdlib" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5c1865780388bfa186411ab5f247819487fc4864c6e9c3106611fa347586e1" +dependencies = [ + "alloc-no-stdlib", +] + +[[package]] +name = "android_system_properties" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc" +dependencies = [ + "libc", +] + +[[package]] +name = "anyhow" +version = "1.0.104" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" + +[[package]] +name = "apple-native-keyring-store" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b350bfd03649e07aa05c0a81b3e15934374e585c98204a57e20b9d49f49bb9a" +dependencies = [ + "keyring-core", + "log", + "security-framework", +] + +[[package]] +name = "arboard" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aeb9553e62312c8756a5979254fc6d7da8bbeb5986a1e17037fab932f7037917" +dependencies = [ + "clipboard-win", + "log", + "objc2", + "objc2-app-kit", + "objc2-foundation", + "parking_lot", + "percent-encoding", + "windows-sys 0.61.2", + "x11rb", +] + +[[package]] +name = "async-broadcast" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532" +dependencies = [ + "event-listener", + "event-listener-strategy", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-channel" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2" +dependencies = [ + "concurrent-queue", + "event-listener-strategy", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-executor" +version = "1.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f426a31126c735126297bc5ea7a521263c9faff4f63ca415267ee625651c4f37" +dependencies = [ + "async-task", + "concurrent-queue", + "fastrand", + "futures-lite", + "pin-project-lite", + "slab", +] + +[[package]] +name = "async-io" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc" +dependencies = [ + "autocfg", + "cfg-if", + "concurrent-queue", + "futures-io", + "futures-lite", + "parking", + "polling", + "rustix", + "slab", + "windows-sys 0.61.2", +] + +[[package]] +name = "async-lock" +version = "3.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0876700b0d007ad25d5508865a4259c3af9af6d296bf663a0d586d0bc3369f6f" +dependencies = [ + "event-listener", + "event-listener-strategy", + "pin-project-lite", +] + +[[package]] +name = "async-process" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75" +dependencies = [ + "async-channel", + "async-io", + "async-lock", + "async-signal", + "async-task", + "blocking", + "cfg-if", + "event-listener", + "futures-lite", + "rustix", +] + +[[package]] +name = "async-recursion" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "async-signal" +version = "0.2.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485" +dependencies = [ + "async-io", + "async-lock", + "atomic-waker", + "cfg-if", + "futures-core", + "futures-io", + "rustix", + "signal-hook-registry", + "slab", + "windows-sys 0.61.2", +] + +[[package]] +name = "async-task" +version = "4.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de" + +[[package]] +name = "async-trait" +version = "0.1.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "atk" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "241b621213072e993be4f6f3a9e4b45f65b7e6faad43001be957184b7bb1824b" +dependencies = [ + "atk-sys", + "glib", + "libc", +] + +[[package]] +name = "atk-sys" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c5e48b684b0ca77d2bbadeef17424c2ea3c897d44d566a1617e7e8f30614d086" +dependencies = [ + "glib-sys", + "gobject-sys", + "libc", + "system-deps", +] + +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "base64" +version = "0.21.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d297deb1925b89f2ccc13d7635fa0714f12c87adce1c75356b39ca9b7178567" + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "base64" +version = "0.23.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5" + +[[package]] +name = "bit-set" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3" +dependencies = [ + "bit-vec 0.8.0", +] + +[[package]] +name = "bit-set" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56d87354e4229f54a44f7bf2435906a4656dba36026ab6eaca629a2c436a691c" +dependencies = [ + "bit-vec 0.10.2", +] + +[[package]] +name = "bit-vec" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7" + +[[package]] +name = "bit-vec" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72503af1e72be411d74ca45cd6b309878fcb35354e252fc2a3a8bda3a97082a0" + +[[package]] +name = "bitflags" +version = "1.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" +dependencies = [ + "serde_core", +] + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "block-buffer" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "block2" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdeb9d870516001442e364c5220d3574d2da8dc765554b4a617230d33fa58ef5" +dependencies = [ + "objc2", +] + +[[package]] +name = "blocking" +version = "1.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa" +dependencies = [ + "async-channel", + "async-task", + "futures-io", + "futures-lite", + "piper", +] + +[[package]] +name = "brotli" +version = "9.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9071f285ed78f04f37d675abaaef5de7689e2f30a216c8dc6795465d81910a13" +dependencies = [ + "alloc-no-stdlib", + "alloc-stdlib", + "brotli-decompressor", +] + +[[package]] +name = "brotli-decompressor" +version = "6.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc031cd87c6529082b0b65c604e86af0ed7744841b17ccfe60b1e31fa606179e" +dependencies = [ + "alloc-no-stdlib", + "alloc-stdlib", +] + +[[package]] +name = "bs58" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf88ba1141d185c399bee5288d850d63b8369520c1eafc32a0430b5b6c287bf4" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "bumpalo" +version = "3.20.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "87a0cf66fd1eb2fb7b822cb78370d82303750809bc6ba855f3f58e517d3238db" + +[[package]] +name = "bytemuck" +version = "1.25.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797" + +[[package]] +name = "byteorder" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" + +[[package]] +name = "bytes" +version = "1.12.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "776dfebd015e2d8732c684a2c71003674ccb49457b539b9e82151ba38e96dd7c" +dependencies = [ + "serde", +] + +[[package]] +name = "cairo-rs" +version = "0.18.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ca26ef0159422fb77631dc9d17b102f253b876fe1586b03b803e63a309b4ee2" +dependencies = [ + "bitflags 2.13.2", + "cairo-sys-rs", + "glib", + "libc", + "once_cell", + "thiserror 1.0.69", +] + +[[package]] +name = "cairo-sys-rs" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "685c9fa8e590b8b3d678873528d83411db17242a73fccaed827770ea0fedda51" +dependencies = [ + "glib-sys", + "libc", + "system-deps", +] + +[[package]] +name = "camino" +version = "1.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbbad30e4b4c14a39e3cc8aed085a12a327257c316619c93581e017bc52be591" +dependencies = [ + "serde_core", +] + +[[package]] +name = "cargo-platform" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e35af189006b9c0f00a064685c727031e3ed2d8020f7ba284d78cc2671bd36ea" +dependencies = [ + "serde", +] + +[[package]] +name = "cargo_metadata" +version = "0.19.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dd5eb614ed4c27c5d706420e4320fbe3216ab31fa1c33cd8246ac36dae4479ba" +dependencies = [ + "camino", + "cargo-platform", + "semver", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "cargo_toml" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82f4b26e751e711a5302649417f2da046dce6391b2ea30a4820f37462314f0b9" +dependencies = [ + "semver", + "serde", + "toml 1.2.1+spec-1.1.0", +] + +[[package]] +name = "cc" +version = "1.11.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33ef9e3e8154a45c7a95cff4c1299702106ad94062d7bb85fdc5d3a5afd91d45" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cesu8" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c" + +[[package]] +name = "cfb" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a347dcabdae9c31b0825fd6a8bed285ec9c2acb89c47827126d52fa4f59cece3" +dependencies = [ + "fnv", + "uuid", + "web-time", +] + +[[package]] +name = "cfg-expr" +version = "0.15.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02" +dependencies = [ + "smallvec", + "target-lexicon", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "chacha20" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "rand_core", +] + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "num-traits", + "serde", + "windows-link", +] + +[[package]] +name = "clipboard-win" +version = "5.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "052af7878466feccda12ba7a6a67d019d712f296809559b47c12c8cc196d3a9a" +dependencies = [ + "error-code", +] + +[[package]] +name = "cmov" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" + +[[package]] +name = "combine" +version = "4.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4356eba6976435498d05a311ee9fc486da3bc81c200d3f0d7dd9703b41913f92" +dependencies = [ + "bytes", + "memchr", +] + +[[package]] +name = "concurrent-queue" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "const-oid" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be95d4a884358a21a199689323c29e9256b4a1b315e22f183d155422041d3a9a" + +[[package]] +name = "cookie" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a373e3602691c3cdea496d2f0ee5935151e6168fe87739483c463db1b2f2f87" +dependencies = [ + "time", + "version_check", +] + +[[package]] +name = "core-foundation" +version = "0.9.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "core-graphics" +version = "0.25.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "064badf302c3194842cf2c5d61f56cc88e54a759313879cdf03abdd27d0c3b97" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.10.1", + "core-graphics-types", + "foreign-types 0.5.0", + "libc", +] + +[[package]] +name = "core-graphics-types" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.10.1", + "libc", +] + +[[package]] +name = "core_detect" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48" + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crc32fast" +version = "1.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b929dd2a135771f40afabd1073f85eed59c800b7c61901e5c254270497dad64" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "crossbeam-channel" +version = "0.5.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "98b0cc327b5bc766e7fda9c9260cc0fa81b43a8e240440422dff70788e3f9ef1" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-utils" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6" + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "crypto-common" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "cssparser" +version = "0.37.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c9cdaae01d5ed7882b04d795e7f752f46ff52d2fa3b50a20d28c464510bba98" +dependencies = [ + "cssparser-macros", + "dtoa-short", + "itoa", + "phf 0.13.1", + "smallvec", +] + +[[package]] +name = "cssparser" +version = "0.38.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "11119743ad110e8c1bdccd930d7f5c30c99e5fc76a7b63ec9807e84eef0c5f59" +dependencies = [ + "cssparser-macros", + "dtoa-short", + "itoa", + "phf 0.14.0", + "smallvec", +] + +[[package]] +name = "cssparser-macros" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d045de693cb712d0b22c6a64be5b953f67b3ce00ab5ad3dd5d8b441886ab8e1a" +dependencies = [ + "quote", + "syn 3.0.10", +] + +[[package]] +name = "ctor" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ea691ed9f36489d087419b8b2ba3ef27d89621380b4178c73e2445a379e4e0f4" +dependencies = [ + "link-section", +] + +[[package]] +name = "ctutils" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "261af4dc7a06ea8a527a8717d8cbba3417530d6ea14e1edb3de6b67806be474f" +dependencies = [ + "cmov", +] + +[[package]] +name = "darling" +version = "0.24.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed17f5901b6630b993ca003def43f2f8ef4014fc13b047b57aad617ff32bc2ec" +dependencies = [ + "darling_core", + "darling_macro", +] + +[[package]] +name = "darling_core" +version = "0.24.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6837e2cf7485aaae18f86181d2f0e9a7ed297a025e220aeabf63fdebd3a2ddff" +dependencies = [ + "ident_case", + "proc-macro2", + "quote", + "strsim", + "syn 3.0.10", +] + +[[package]] +name = "darling_macro" +version = "0.24.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ac7135c3ef02b2f7833bbeb1be5ba7f966dcde8a87c6b87f65a778d71a02785" +dependencies = [ + "darling_core", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "dbus" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ab69f03cc8c4340c9c8e315114e1658e6775a9b16a04357973aa21cec22b32e" +dependencies = [ + "libc", + "libdbus-sys", + "windows-sys 0.61.2", +] + +[[package]] +name = "deranged" +version = "0.5.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e9de72ce2ad1f90dc62fa25f0f430ef85eb4b0d8fa0be4f30373bc40a21d28e" +dependencies = [ + "serde_core", +] + +[[package]] +name = "derive_more" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134" +dependencies = [ + "derive_more-impl", +] + +[[package]] +name = "derive_more-impl" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb" +dependencies = [ + "proc-macro2", + "quote", + "rustc_version", + "syn 2.0.119", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer 0.10.4", + "crypto-common 0.1.7", +] + +[[package]] +name = "digest" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2" +dependencies = [ + "block-buffer 0.12.1", + "const-oid", + "crypto-common 0.2.2", + "ctutils", +] + +[[package]] +name = "dirs" +version = "7.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d57d423b3c82e89b9a24ca3091fee61f456a26edbd28d26c65906f4bc1dcd8f" +dependencies = [ + "dirs-sys", +] + +[[package]] +name = "dirs-sys" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab" +dependencies = [ + "libc", + "option-ext", + "redox_users", + "windows-sys 0.61.2", +] + +[[package]] +name = "dispatch2" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38" +dependencies = [ + "bitflags 2.13.2", + "block2", + "libc", + "objc2", +] + +[[package]] +name = "displaydoc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "dlopen2" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e2c5bd4158e66d1e215c49b837e11d62f3267b30c92f1d171c4d3105e3dc4d4" +dependencies = [ + "dlopen2_derive", + "libc", + "once_cell", + "winapi", +] + +[[package]] +name = "dlopen2_derive" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fbbb781877580993a8707ec48672673ec7b81eeba04cfd2310bd28c08e47c8f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "dom_query" +version = "0.28.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fac5fca71e65e94cc718a6e2af65d6e0f9c6027751c2aa562fbb5087fda639bc" +dependencies = [ + "bit-set 0.8.0", + "cssparser 0.37.0", + "foldhash", + "html5ever 0.39.0", + "precomputed-hash", + "selectors 0.38.0", + "tendril", +] + +[[package]] +name = "dom_query" +version = "0.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "498c698ac51127148a3984450e51fca7f01805a91d7a1f7a24af0a5f761e3385" +dependencies = [ + "bit-set 0.11.1", + "cssparser 0.38.0", + "foldhash", + "html5ever 0.40.1", + "precomputed-hash", + "selectors 0.41.0", + "tendril", +] + +[[package]] +name = "dpi" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76" +dependencies = [ + "serde", +] + +[[package]] +name = "dtoa" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590" + +[[package]] +name = "dtoa-short" +version = "0.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd1511a7b6a56299bd043a9c167a6d2bfb37bf84a6dfceaba651168adfb43c87" +dependencies = [ + "dtoa", +] + +[[package]] +name = "dunce" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" + +[[package]] +name = "dyn-clone" +version = "1.0.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555" + +[[package]] +name = "embed-resource" +version = "3.0.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6168487b5e7eb2673e6efe1200b1848016e436a6ca0b8031bf04bd9d493a249f" +dependencies = [ + "cc", + "memchr", + "rustc_version", + "toml 1.2.1+spec-1.1.0", + "vswhom", + "winreg", +] + +[[package]] +name = "embed_plist" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ef6b89e5b37196644d8796de5268852ff179b44e96276cf4290264843743bb7" + +[[package]] +name = "encoding_rs" +version = "0.8.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "89253175e704ab869b04f9db224d38630e0211a53841a79181deae0889e169f5" +dependencies = [ + "cfg-if", + "core_detect", + "multiversion_no_op", + "rustversion", + "scopeguard", + "simdutf8", +] + +[[package]] +name = "endi" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099" + +[[package]] +name = "enumflags2" +version = "0.7.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef" +dependencies = [ + "enumflags2_derive", + "serde", +] + +[[package]] +name = "enumflags2_derive" +version = "0.7.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "erased-serde" +version = "0.4.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e59b668157f32d3459d4bd634861a06ffa2503a461ca5f0916b9f0252605e66" +dependencies = [ + "serde", + "serde_core", + "typeid", +] + +[[package]] +name = "errno" +version = "0.3.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e35d6e78f4cebb90e51d543db8fe41528851d6deeef6ef21ebd4bfdc1e784776" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "error-code" +version = "3.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7" + +[[package]] +name = "event-listener" +version = "5.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2" +dependencies = [ + "parking", + "pin-project-lite", +] + +[[package]] +name = "event-listener-strategy" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93" +dependencies = [ + "event-listener", + "pin-project-lite", +] + +[[package]] +name = "fallible-iterator" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4443176a9f2c162692bd3d352d745ef9413eec5782a80d8fd6f8a1ac692a07f7" + +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + +[[package]] +name = "fdeflate" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c" +dependencies = [ + "simd-adler32", +] + +[[package]] +name = "field-offset" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38e2275cc4e4fc009b0669731a1e5ab7ebf11f469eaede2bab9309a5b4d6057f" +dependencies = [ + "memoffset", + "rustc_version", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "flate2" +version = "1.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "626d4928326b646e70f65ed36fc7cf9f206bdb68a0019ee7c6b4709da4e084c4" +dependencies = [ + "crc32fast", + "miniz_oxide 0.9.1", + "zlib-rs", +] + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "foreign-types" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1" +dependencies = [ + "foreign-types-shared 0.1.1", +] + +[[package]] +name = "foreign-types" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965" +dependencies = [ + "foreign-types-macros", + "foreign-types-shared 0.3.1", +] + +[[package]] +name = "foreign-types-macros" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ea5190182e6915eb873ddbc16e23b711b6eb1f9c00a0d0a3a91b5f6228475225" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "foreign-types-shared" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b" + +[[package]] +name = "foreign-types-shared" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-executor" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" + +[[package]] +name = "futures-lite" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad" +dependencies = [ + "fastrand", + "futures-core", + "futures-io", + "parking", + "pin-project-lite", +] + +[[package]] +name = "futures-macro" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "futures-sink" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "gdk" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9f245958c627ac99d8e529166f9823fb3b838d1d41fd2b297af3075093c2691" +dependencies = [ + "cairo-rs", + "gdk-pixbuf", + "gdk-sys", + "gio", + "glib", + "libc", + "pango", +] + +[[package]] +name = "gdk-pixbuf" +version = "0.18.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "50e1f5f1b0bfb830d6ccc8066d18db35c487b1b2b1e8589b5dfe9f07e8defaec" +dependencies = [ + "gdk-pixbuf-sys", + "gio", + "glib", + "libc", + "once_cell", +] + +[[package]] +name = "gdk-pixbuf-sys" +version = "0.18.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9839ea644ed9c97a34d129ad56d38a25e6756f99f3a88e15cd39c20629caf7" +dependencies = [ + "gio-sys", + "glib-sys", + "gobject-sys", + "libc", + "system-deps", +] + +[[package]] +name = "gdk-sys" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c2d13f38594ac1e66619e188c6d5a1adb98d11b2fcf7894fc416ad76aa2f3f7" +dependencies = [ + "cairo-sys-rs", + "gdk-pixbuf-sys", + "gio-sys", + "glib-sys", + "gobject-sys", + "libc", + "pango-sys", + "pkg-config", + "system-deps", +] + +[[package]] +name = "gdkwayland-sys" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "140071d506d223f7572b9f09b5e155afbd77428cd5cc7af8f2694c41d98dfe69" +dependencies = [ + "gdk-sys", + "glib-sys", + "gobject-sys", + "libc", + "pkg-config", + "system-deps", +] + +[[package]] +name = "gdkx11" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3caa00e14351bebbc8183b3c36690327eb77c49abc2268dd4bd36b856db3fbfe" +dependencies = [ + "gdk", + "gdkx11-sys", + "gio", + "glib", + "libc", + "x11", +] + +[[package]] +name = "gdkx11-sys" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2e7445fe01ac26f11601db260dd8608fe172514eb63b3b5e261ea6b0f4428d" +dependencies = [ + "gdk-sys", + "glib-sys", + "libc", + "system-deps", + "x11", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "gethostname" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8" +dependencies = [ + "rustix", + "windows-link", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "libc", + "wasi 0.11.1+wasi-snapshot-preview1", +] + +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi 5.3.0", + "wasip2", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi 6.0.0", + "rand_core", +] + +[[package]] +name = "gio" +version = "0.18.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4fc8f532f87b79cbc51a79748f16a6828fb784be93145a322fa14d06d354c73" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-util", + "gio-sys", + "glib", + "libc", + "once_cell", + "pin-project-lite", + "smallvec", + "thiserror 1.0.69", +] + +[[package]] +name = "gio-sys" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "37566df850baf5e4cb0dfb78af2e4b9898d817ed9263d1090a2df958c64737d2" +dependencies = [ + "glib-sys", + "gobject-sys", + "libc", + "system-deps", + "winapi", +] + +[[package]] +name = "glib" +version = "0.18.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "233daaf6e83ae6a12a52055f568f9d7cf4671dabb78ff9560ab6da230ce00ee5" +dependencies = [ + "bitflags 2.13.2", + "futures-channel", + "futures-core", + "futures-executor", + "futures-task", + "futures-util", + "gio-sys", + "glib-macros", + "glib-sys", + "gobject-sys", + "libc", + "memchr", + "once_cell", + "smallvec", + "thiserror 1.0.69", +] + +[[package]] +name = "glib-macros" +version = "0.18.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bb0228f477c0900c880fd78c8759b95c7636dbd7842707f49e132378aa2acdc" +dependencies = [ + "heck 0.4.1", + "proc-macro-crate 2.0.2", + "proc-macro-error", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "glib-sys" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "063ce2eb6a8d0ea93d2bf8ba1957e78dbab6be1c2220dd3daca57d5a9d869898" +dependencies = [ + "libc", + "system-deps", +] + +[[package]] +name = "glob" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b" + +[[package]] +name = "gobject-sys" +version = "0.18.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0850127b514d1c4a4654ead6dedadb18198999985908e6ffe4436f53c785ce44" +dependencies = [ + "glib-sys", + "libc", + "system-deps", +] + +[[package]] +name = "gtk" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd56fb197bfc42bd5d2751f4f017d44ff59fbb58140c6b49f9b3b2bdab08506a" +dependencies = [ + "atk", + "cairo-rs", + "field-offset", + "futures-channel", + "gdk", + "gdk-pixbuf", + "gio", + "glib", + "gtk-sys", + "gtk3-macros", + "libc", + "pango", + "pkg-config", +] + +[[package]] +name = "gtk-sys" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f29a1c21c59553eb7dd40e918be54dccd60c52b049b75119d5d96ce6b624414" +dependencies = [ + "atk-sys", + "cairo-sys-rs", + "gdk-pixbuf-sys", + "gdk-sys", + "gio-sys", + "glib-sys", + "gobject-sys", + "libc", + "pango-sys", + "system-deps", +] + +[[package]] +name = "gtk3-macros" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52ff3c5b21f14f0736fed6dcfc0bfb4225ebf5725f3c0209edeec181e4d73e9d" +dependencies = [ + "proc-macro-crate 1.3.1", + "proc-macro-error", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "h2" +version = "0.4.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118" +dependencies = [ + "atomic-waker", + "bytes", + "fnv", + "futures-core", + "futures-sink", + "http", + "indexmap 2.14.2", + "slab", + "tokio", + "tokio-util", + "tracing", +] + +[[package]] +name = "hashbrown" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888" + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "heck" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "hermit-abi" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284" + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hmac" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f" +dependencies = [ + "digest 0.11.3", +] + +[[package]] +name = "html5ever" +version = "0.39.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "46a1761807faccc9a19e86944bbf40610014066306f96edcdedc2fb714bcb7b8" +dependencies = [ + "log", + "markup5ever 0.39.0", +] + +[[package]] +name = "html5ever" +version = "0.40.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "456a1a377e608e555d22ddab27ac0114bc7a7b4199078108e34c2aeae6c9b130" +dependencies = [ + "log", + "markup5ever 0.40.0", + "memchr", +] + +[[package]] +name = "http" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "hybrid-array" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17" +dependencies = [ + "typenum", +] + +[[package]] +name = "hyper" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c" +dependencies = [ + "atomic-waker", + "bytes", + "futures-channel", + "futures-core", + "h2", + "http", + "http-body", + "httparse", + "itoa", + "pin-project-lite", + "smallvec", + "tokio", + "want", +] + +[[package]] +name = "hyper-rustls" +version = "0.27.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dfa8e654703247911e29c23fbeaa261834bd9bb74efba2f9acddc37bfb127f53" +dependencies = [ + "http", + "hyper", + "hyper-util", + "rustls", + "tokio", + "tokio-rustls", + "tower-service", +] + +[[package]] +name = "hyper-tls" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "70206fc6890eaca9fde8a0bf71caa2ddfc9fe045ac9e5c70df101a7dbde866e0" +dependencies = [ + "bytes", + "http-body-util", + "hyper", + "hyper-util", + "native-tls", + "tokio", + "tokio-native-tls", + "tower-service", +] + +[[package]] +name = "hyper-util" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff" +dependencies = [ + "base64 0.23.1", + "bytes", + "futures-channel", + "futures-util", + "http", + "http-body", + "httparse", + "hyper", + "ipnet", + "libc", + "percent-encoding", + "pin-project-lite", + "socket2", + "system-configuration", + "tokio", + "tower-service", + "tracing", + "windows-registry", +] + +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + +[[package]] +name = "ico" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d75e94d66081e4d8dcd098bd8dc5254800fea14a26389b298410158d834de167" +dependencies = [ + "byteorder", + "png", +] + +[[package]] +name = "icu_collections" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe090a42a0d3140fed8c63263ed1fecc02422cb2f4bfe55cd8de2de1b8e105dd" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25d29b57c17c6528d0dc4c2141cfa2d08200465acb537a3909c8b9b8a4a984c0" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "404a3b8c486f205c87fe7f23ab6894d84a4ad76d6e4671ae1981ba7def87c599" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20f0088bfb7441f7a37fa0c9e20cb1e9cba1cac6b9ce8cd2a6dc44294f8e8cbc" + +[[package]] +name = "icu_properties" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ea83d991c56158f7cf898bf86436c1dfe7c07ee82fe88951f2695c9f37a379f" +dependencies = [ + "displaydoc", + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b98f29af82d02b163fe50161388350e743bb3107cc8e8c2f7314cb505faddfcf" + +[[package]] +name = "icu_provider" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413099315636c588ee8f011190b329b971a09a8fae9d157e01dcae8379468514" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "ident_case" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39" + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "indexmap" +version = "1.9.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99" +dependencies = [ + "autocfg", + "hashbrown 0.12.3", + "serde", +] + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown 0.17.1", + "serde", + "serde_core", +] + +[[package]] +name = "infer" +version = "0.22.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f4200d433cbd5178df7797c9c2e75b348b728e39631cf14520d1e2fc424201f4" +dependencies = [ + "cfb", +] + +[[package]] +name = "ipnet" +version = "2.12.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0" + +[[package]] +name = "is-docker" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "928bae27f42bc99b60d9ac7334e3a21d10ad8f1835a4e12ec3ec0464765ed1b3" +dependencies = [ + "once_cell", +] + +[[package]] +name = "is-wsl" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "173609498df190136aa7dea1a91db051746d339e18476eed5ca40521f02d7aa5" +dependencies = [ + "is-docker", + "once_cell", +] + +[[package]] +name = "itoa" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4" + +[[package]] +name = "javascriptcore-rs" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca5671e9ffce8ffba57afc24070e906da7fc4b1ba66f2cabebf61bf2ea257fcc" +dependencies = [ + "bitflags 1.3.2", + "glib", + "javascriptcore-rs-sys", +] + +[[package]] +name = "javascriptcore-rs-sys" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af1be78d14ffa4b75b66df31840478fef72b51f8c2465d4ca7c194da9f7a5124" +dependencies = [ + "glib-sys", + "gobject-sys", + "libc", + "system-deps", +] + +[[package]] +name = "jiff" +version = "0.2.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "175dc66334db3b9ab9985bf8b61cfed50dc16d20964bb47f9e479adcae984a7f" +dependencies = [ + "jiff-core", + "jiff-static", + "jiff-tzdb-platform", + "log", + "portable-atomic", + "portable-atomic-util", + "serde_core", + "windows-link", +] + +[[package]] +name = "jiff-core" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e599b80292e597019b8b3e392de3f4bea2959ddfb8c7dff60e035e9e311a2c1b" +dependencies = [ + "log", +] + +[[package]] +name = "jiff-static" +version = "0.2.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c7b1af7547d47354bc438d797e3854601bde8f8d185780c5ba4ab27afa54f1ba" +dependencies = [ + "jiff-core", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "jiff-tzdb" +version = "0.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0980fca2cc272465bd60e82397607ba9f33add9e48defd77923301bbd03808f2" + +[[package]] +name = "jiff-tzdb-platform" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "875a5a69ac2bab1a891711cf5eccbec1ce0341ea805560dcd90b7a2e925132e8" +dependencies = [ + "jiff-tzdb", +] + +[[package]] +name = "jni" +version = "0.21.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a87aa2bb7d2af34197c04845522473242e1aa17c12f4935d5856491a7fb8c97" +dependencies = [ + "cesu8", + "cfg-if", + "combine", + "jni-sys 0.3.1", + "log", + "thiserror 1.0.69", + "walkdir", + "windows-sys 0.45.0", +] + +[[package]] +name = "jni-sys" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258" +dependencies = [ + "jni-sys 0.4.1", +] + +[[package]] +name = "jni-sys" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2" +dependencies = [ + "jni-sys-macros", +] + +[[package]] +name = "jni-sys-macros" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264" +dependencies = [ + "quote", + "syn 2.0.119", +] + +[[package]] +name = "js-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + +[[package]] +name = "json-patch" +version = "4.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7421438de105a0827e44fadd05377727847d717c80ce29a229f85fd04c427b72" +dependencies = [ + "jsonptr", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "jsonptr" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5a3cc660ba5d72bce0b3bb295bf20847ccbb40fd423f3f05b61273672e561fe" +dependencies = [ + "serde", + "serde_json", +] + +[[package]] +name = "keyboard-types" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fbe853b403ae61a04233030ae8a79d94975281ed9770a1f9e246732b534b28d" +dependencies = [ + "bitflags 2.13.2", + "serde", +] + +[[package]] +name = "keyring-core" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29fbf4b551298c67925f38cf341a1ada797a75f1837bdf8ae1fc8e2ebc6efb59" +dependencies = [ + "log", +] + +[[package]] +name = "libappindicator" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03589b9607c868cc7ae54c0b2a22c8dc03dd41692d48f2d7df73615c6a95dc0a" +dependencies = [ + "glib", + "gtk", + "gtk-sys", + "libappindicator-sys", + "log", +] + +[[package]] +name = "libappindicator-sys" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e9ec52138abedcc58dc17a7c6c0c00a2bdb4f3427c7f63fa97fd0d859155caf" +dependencies = [ + "gtk-sys", + "libloading", + "once_cell", +] + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "libdbus-sys" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "328c4789d42200f1eeec05bd86c9c13c7f091d2ba9a6ea35acdf51f31bc0f043" +dependencies = [ + "pkg-config", +] + +[[package]] +name = "libloading" +version = "0.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67380fd3b2fbe7527a606e18729d21c6f3951633d0500574c4dc22d2d638b9f" +dependencies = [ + "cfg-if", + "winapi", +] + +[[package]] +name = "libredox" +version = "0.1.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61ff90caf6077a803a240f62fdbe88645a890bbca49ef8174c3cb0404362171d" +dependencies = [ + "libc", +] + +[[package]] +name = "link-section" +version = "0.19.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4d9aae57673c1a235149777a74d152f3210ebd3e3b13346d2cdb6809e566bd3c" + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "litemap" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" + +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + +[[package]] +name = "log" +version = "0.4.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c" + +[[package]] +name = "markup5ever" +version = "0.39.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7122d987ec5f704ee56f6e5b41a7d93722e9aae27ae07cafa4036c4d3f9757de" +dependencies = [ + "log", + "tendril", + "web_atoms 0.2.6", +] + +[[package]] +name = "markup5ever" +version = "0.40.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ab3dc68ac4a0f5719e560136778c1ee716e296030d75dbd4484e37e39e3a842" +dependencies = [ + "log", + "tendril", + "web_atoms 0.3.0", +] + +[[package]] +name = "md-5" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69b6441f590336821bb897fb28fc622898ccceb1d6cea3fde5ea86b090c4de98" +dependencies = [ + "cfg-if", + "digest 0.11.3", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "memoffset" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a" +dependencies = [ + "autocfg", +] + +[[package]] +name = "mime" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d5848f5a9e8117cf94f2f90faac24a87ff81600ff8628c1e3deaab572e76bfa1" + +[[package]] +name = "miniz_oxide" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "miniz_oxide" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "mio" +version = "1.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20521a903f02b0a573cd6840e9d0a5a0cc043d361fe924092cd70f8556cc9c4a" +dependencies = [ + "libc", + "wasi 0.11.1+wasi-snapshot-preview1", + "windows-sys 0.61.2", +] + +[[package]] +name = "muda" +version = "0.20.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cca139e57da4383727f189e43e66e84fa372347027fc996f9f1a007ec0a37996" +dependencies = [ + "crossbeam-channel", + "dpi", + "gtk", + "keyboard-types", + "objc2", + "objc2-app-kit", + "objc2-core-foundation", + "objc2-foundation", + "once_cell", + "png", + "serde", + "thiserror 2.0.21", + "windows-sys 0.61.2", +] + +[[package]] +name = "multiversion_no_op" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d" + +[[package]] +name = "native-tls" +version = "0.2.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "465500e14ea162429d264d44189adc38b199b62b1c21eea9f69e4b73cb03bbf2" +dependencies = [ + "libc", + "log", + "openssl", + "openssl-probe", + "openssl-sys", + "schannel", + "security-framework", + "security-framework-sys", + "tempfile", +] + +[[package]] +name = "ndk" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4" +dependencies = [ + "bitflags 2.13.2", + "jni-sys 0.3.1", + "log", + "ndk-sys", + "num_enum", + "raw-window-handle", + "thiserror 1.0.69", +] + +[[package]] +name = "ndk-context" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27b02d87554356db9e9a873add8782d4ea6e3e58ea071a9adb9a2e8ddb884a8b" + +[[package]] +name = "ndk-sys" +version = "0.6.0+11769913" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee6cda3051665f1fb8d9e08fc35c96d5a244fb1be711a03b71118828afc9a873" +dependencies = [ + "jni-sys 0.3.1", +] + +[[package]] +name = "new_debug_unreachable" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086" + +[[package]] +name = "num-conv" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "num_enum" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26" +dependencies = [ + "num_enum_derive", + "rustversion", +] + +[[package]] +name = "num_enum_derive" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8" +dependencies = [ + "proc-macro-crate 3.5.0", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "objc2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08849bbd4767dfae9457696856ae1c84fe4e0281bbe4a7abff2d0e06fb7981f8" +dependencies = [ + "objc2-encode", + "objc2-exception-helper", +] + +[[package]] +name = "objc2-app-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c" +dependencies = [ + "bitflags 2.13.2", + "block2", + "objc2", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-foundation", + "objc2-quartz-core", +] + +[[package]] +name = "objc2-cloud-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c" +dependencies = [ + "bitflags 2.13.2", + "objc2", + "objc2-foundation", +] + +[[package]] +name = "objc2-core-data" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa" +dependencies = [ + "objc2", + "objc2-foundation", +] + +[[package]] +name = "objc2-core-foundation" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536" +dependencies = [ + "bitflags 2.13.2", + "dispatch2", + "objc2", +] + +[[package]] +name = "objc2-core-graphics" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807" +dependencies = [ + "bitflags 2.13.2", + "dispatch2", + "objc2", + "objc2-core-foundation", + "objc2-io-surface", +] + +[[package]] +name = "objc2-core-image" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5d563b38d2b97209f8e861173de434bd0214cf020e3423a52624cd1d989f006" +dependencies = [ + "objc2", + "objc2-foundation", +] + +[[package]] +name = "objc2-core-location" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca347214e24bc973fc025fd0d36ebb179ff30536ed1f80252706db19ee452009" +dependencies = [ + "objc2", + "objc2-foundation", +] + +[[package]] +name = "objc2-core-text" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d" +dependencies = [ + "bitflags 2.13.2", + "objc2", + "objc2-core-foundation", + "objc2-core-graphics", +] + +[[package]] +name = "objc2-encode" +version = "4.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33" + +[[package]] +name = "objc2-exception-helper" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c7a1c5fbb72d7735b076bb47b578523aedc40f3c439bea6dfd595c089d79d98a" +dependencies = [ + "cc", +] + +[[package]] +name = "objc2-foundation" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272" +dependencies = [ + "bitflags 2.13.2", + "block2", + "libc", + "objc2", + "objc2-core-foundation", +] + +[[package]] +name = "objc2-io-surface" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d" +dependencies = [ + "bitflags 2.13.2", + "objc2", + "objc2-core-foundation", +] + +[[package]] +name = "objc2-quartz-core" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "96c1358452b371bf9f104e21ec536d37a650eb10f7ee379fff67d2e08d537f1f" +dependencies = [ + "bitflags 2.13.2", + "objc2", + "objc2-core-foundation", + "objc2-foundation", +] + +[[package]] +name = "objc2-system-configuration" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7216bd11cbda54ccabcab84d523dc93b858ec75ecfb3a7d89513fa22464da396" +dependencies = [ + "objc2-core-foundation", +] + +[[package]] +name = "objc2-ui-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d87d638e33c06f577498cbcc50491496a3ed4246998a7fbba7ccb98b1e7eab22" +dependencies = [ + "bitflags 2.13.2", + "block2", + "objc2", + "objc2-cloud-kit", + "objc2-core-data", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-core-image", + "objc2-core-location", + "objc2-core-text", + "objc2-foundation", + "objc2-quartz-core", + "objc2-user-notifications", +] + +[[package]] +name = "objc2-user-notifications" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9df9128cbbfef73cda168416ccf7f837b62737d748333bfe9ab71c245d76613e" +dependencies = [ + "objc2", + "objc2-foundation", +] + +[[package]] +name = "objc2-web-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2e5aaab980c433cf470df9d7af96a7b46a9d892d521a2cbbb2f8a4c16751e7f" +dependencies = [ + "bitflags 2.13.2", + "block2", + "objc2", + "objc2-app-kit", + "objc2-core-foundation", + "objc2-foundation", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "open" +version = "5.4.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d8c8b8e725ad26404d6896eb2f064294a0a7b4f1d9120210d85544684c4ca95" +dependencies = [ + "dunce", + "is-wsl", + "libc", +] + +[[package]] +name = "openssl" +version = "0.10.82" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4de8111e94a56adca7ebfe6c365b6d42f99deb69b74b6becacd4204e2f193aa2" +dependencies = [ + "bitflags 2.13.2", + "cfg-if", + "foreign-types 0.3.2", + "libc", + "openssl-macros", + "openssl-sys", +] + +[[package]] +name = "openssl-macros" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "openssl-probe" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e036b411754132fd6b74e94b74e9a13c5cf606fa93d1885c35860d3060820b1" + +[[package]] +name = "openssl-sys" +version = "0.9.118" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19c413d6ec9ebaf5e1c829d355cb3e9f783778d700f135be0921d52fce3c60ae" +dependencies = [ + "cc", + "libc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "option-ext" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d" + +[[package]] +name = "ordered-stream" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50" +dependencies = [ + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "pango" +version = "0.18.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ca27ec1eb0457ab26f3036ea52229edbdb74dee1edd29063f5b9b010e7ebee4" +dependencies = [ + "gio", + "glib", + "libc", + "once_cell", + "pango-sys", +] + +[[package]] +name = "pango-sys" +version = "0.18.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "436737e391a843e5933d6d9aa102cb126d501e815b83601365a948a518555dc5" +dependencies = [ + "glib-sys", + "gobject-sys", + "libc", + "system-deps", +] + +[[package]] +name = "parking" +version = "2.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba" + +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link", +] + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "phf" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1562dc717473dbaa4c1f85a36410e03c047b2e7df7f45ee938fbef64ae7fadf" +dependencies = [ + "phf_macros 0.13.1", + "phf_shared 0.13.1", + "serde", +] + +[[package]] +name = "phf" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "010378780309880b08997fae13be7834dba947d36393bd372f2b1556deb2a2f6" +dependencies = [ + "phf_macros 0.14.0", + "phf_shared 0.14.0", + "serde", +] + +[[package]] +name = "phf_codegen" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49aa7f9d80421bca176ca8dbfebe668cc7a2684708594ec9f3c0db0805d5d6e1" +dependencies = [ + "phf_generator 0.13.1", + "phf_shared 0.13.1", +] + +[[package]] +name = "phf_codegen" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41b585a510fb76fdebead6897982ef2a03a21d8e6cbcca904999742a4afc6ffe" +dependencies = [ + "phf_generator 0.14.0", + "phf_shared 0.14.0", +] + +[[package]] +name = "phf_generator" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "135ace3a761e564ec88c03a77317a7c6b80bb7f7135ef2544dbe054243b89737" +dependencies = [ + "fastrand", + "phf_shared 0.13.1", +] + +[[package]] +name = "phf_generator" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aeb62e0959d5a1bebc965f4d15d9e2b7cea002b6b0f5ba8cde6cc26738467100" +dependencies = [ + "fastrand", + "phf_shared 0.14.0", +] + +[[package]] +name = "phf_macros" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "812f032b54b1e759ccd5f8b6677695d5268c588701effba24601f6932f8269ef" +dependencies = [ + "phf_generator 0.13.1", + "phf_shared 0.13.1", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "phf_macros" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5fa8d0ca26d424d27630da600c6624696e7dec8bf7b3b492b383c5dc49e5e085" +dependencies = [ + "phf_generator 0.14.0", + "phf_shared 0.14.0", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "phf_shared" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e57fef6bc5981e38c2ce2d63bfa546861309f875b8a75f092d1d54ae2d64f266" +dependencies = [ + "siphasher", +] + +[[package]] +name = "phf_shared" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6fd9027e2d9319be6349febd1db4e8d02aa544921200c9b777720ac34a3aa89" +dependencies = [ + "siphasher", +] + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "piper" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1" +dependencies = [ + "atomic-waker", + "fastrand", + "futures-io", +] + +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + +[[package]] +name = "plist" +version = "1.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d86a77b7d9cdebd9643c180c158748db7d894b24a3935ed4b5843e698ae086eb" +dependencies = [ + "base64 0.23.1", + "indexmap 2.14.2", + "quick-xml", + "serde", + "time", +] + +[[package]] +name = "png" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61" +dependencies = [ + "bitflags 2.13.2", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide 0.8.9", +] + +[[package]] +name = "polling" +version = "3.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d0e4f59085d47d8241c88ead0f274e8a0cb551f3625263c05eb8dd897c34218" +dependencies = [ + "cfg-if", + "concurrent-queue", + "hermit-abi", + "pin-project-lite", + "rustix", + "windows-sys 0.61.2", +] + +[[package]] +name = "portable-atomic" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85" + +[[package]] +name = "portable-atomic-util" +version = "0.2.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715" +dependencies = [ + "portable-atomic", +] + +[[package]] +name = "postgres-protocol" +version = "0.6.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08808e3c483c46e999108051c78334f473d5adb59d78bb80a1268c7e6aa6c514" +dependencies = [ + "base64 0.22.1", + "byteorder", + "bytes", + "fallible-iterator", + "hmac", + "md-5", + "memchr", + "rand", + "sha2 0.11.1", + "stringprep", +] + +[[package]] +name = "postgres-types" +version = "0.2.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "851ca9db4932932d69f3ea811b1abe63087a0f740a47692619dd40d4899b68be" +dependencies = [ + "bytes", + "fallible-iterator", + "postgres-protocol", +] + +[[package]] +name = "potential_utf" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" +dependencies = [ + "zerovec", +] + +[[package]] +name = "powerfmt" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a6394b9e965e73d0a289ee54f589087e2c676aedf60885baf52c76b771e4958" + +[[package]] +name = "precomputed-hash" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c" + +[[package]] +name = "proc-macro-crate" +version = "1.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f4c021e1093a56626774e81216a4ce732a735e5bad4868a03f3ed65ca0c3919" +dependencies = [ + "once_cell", + "toml_edit 0.19.15", +] + +[[package]] +name = "proc-macro-crate" +version = "2.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b00f26d3400549137f92511a46ac1cd8ce37cb5598a96d382381458b992a5d24" +dependencies = [ + "toml_datetime 0.6.3", + "toml_edit 0.20.2", +] + +[[package]] +name = "proc-macro-crate" +version = "3.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f" +dependencies = [ + "toml_edit 0.25.19+spec-1.1.0", +] + +[[package]] +name = "proc-macro-error" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da25490ff9892aab3fcf7c36f08cfb902dd3e71ca0f9f9517bea02a73a5ce38c" +dependencies = [ + "proc-macro-error-attr", + "proc-macro2", + "quote", + "syn 1.0.109", + "version_check", +] + +[[package]] +name = "proc-macro-error-attr" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1be40180e52ecc98ad80b184934baf3d0d29f979574e439af5a55274b35f869" +dependencies = [ + "proc-macro2", + "quote", + "version_check", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quick-xml" +version = "0.42.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41b1177fdf999d2321d3fb46ff47159d9c1fb9ad66a4879f8c50a0b504615e9b" +dependencies = [ + "memchr", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "rand" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f6fa277c67e6ea590466f04c3fe82cb509f0864fe470643e5570de9514a9b11" +dependencies = [ + "chacha20", + "getrandom 0.4.3", + "rand_core", +] + +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + +[[package]] +name = "raw-window-handle" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539" + +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags 2.13.2", +] + +[[package]] +name = "redox_users" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60dc65c0ff1a7ae1294b0c67b9f14baf70b644404010370171787bfac1038fc0" +dependencies = [ + "libredox", + "thiserror 2.0.21", +] + +[[package]] +name = "ref-cast" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3" +dependencies = [ + "ref-cast-impl", +] + +[[package]] +name = "ref-cast-impl" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "regex" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "reqwest" +version = "0.13.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "16a1cfa75cc186dd73d5818e510e042e40927bccc9c236b061cea97e1eb08029" +dependencies = [ + "base64 0.23.1", + "bytes", + "encoding_rs", + "futures-core", + "futures-util", + "h2", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-rustls", + "hyper-tls", + "hyper-util", + "js-sys", + "log", + "mime", + "native-tls", + "percent-encoding", + "pin-project-lite", + "rustls-pki-types", + "serde", + "serde_json", + "sync_wrapper", + "tokio", + "tokio-native-tls", + "tokio-util", + "tower", + "tower-http", + "tower-service", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-streams", + "web-sys", +] + +[[package]] +name = "rfd" +version = "0.17.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20dafead71c16a34e1ff357ddefc8afc11e7d51d6d2b9fbd07eaa48e3e540220" +dependencies = [ + "block2", + "dispatch2", + "glib-sys", + "gobject-sys", + "gtk-sys", + "js-sys", + "libc", + "log", + "objc2", + "objc2-app-kit", + "objc2-core-foundation", + "objc2-foundation", + "percent-encoding", + "raw-window-handle", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", + "windows-sys 0.61.2", +] + +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom 0.2.17", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + +[[package]] +name = "rmcp" +version = "3.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "391f153431ab68664d946513ea0cb3edbca78eaf99c5a983036cacab6220d85b" +dependencies = [ + "chrono", + "futures", + "indexmap 2.14.2", + "libc", + "percent-encoding", + "pin-project-lite", + "serde", + "serde_json", + "sha2 0.11.1", + "thiserror 2.0.21", + "tokio", + "tokio-stream", + "tokio-util", + "tracing", + "unicode-general-category", + "unicode-normalization", +] + +[[package]] +name = "rustc-hash" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d" + +[[package]] +name = "rustc_version" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92" +dependencies = [ + "semver", +] + +[[package]] +name = "rustix" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" +dependencies = [ + "bitflags 2.13.2", + "errno", + "libc", + "linux-raw-sys", + "windows-sys 0.61.2", +] + +[[package]] +name = "rustls" +version = "0.23.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf" +dependencies = [ + "once_cell", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-pki-types" +version = "1.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "102f35f7de7b06d8c61f1cff6592f5253e0dea431c74867aad5dfd70f44663fb" +dependencies = [ + "zeroize", +] + +[[package]] +name = "rustls-webpki" +version = "0.103.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3a0760a887c14823fca5a1c970b01d47c328c696c0c64829d1df50e8f853fd5" +dependencies = [ + "ring", + "rustls-pki-types", + "untrusted", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "schannel" +version = "0.1.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9cb23c424d8ee841bb4d813677ca237e2a610067d594fec130f87d6093495ab5" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "schemars" +version = "0.8.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3fbf2ae1b8bc8e02df939598064d22402220cd5bbcca1c76f7d6a310974d5615" +dependencies = [ + "dyn-clone", + "indexmap 1.9.3", + "schemars_derive", + "serde", + "serde_json", + "url", + "uuid", +] + +[[package]] +name = "schemars" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4cd191f9397d57d581cddd31014772520aa448f65ef991055d7f61582c65165f" +dependencies = [ + "dyn-clone", + "ref-cast", + "serde", + "serde_json", +] + +[[package]] +name = "schemars" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab508826f74a77ca9d5aba6ff19b522583ee3eaf28a19384ff3d0e5835fadf6e" +dependencies = [ + "dyn-clone", + "ref-cast", + "serde", + "serde_json", +] + +[[package]] +name = "schemars_derive" +version = "0.8.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32e265784ad618884abaea0600a9adf15393368d840e0222d101a072f3f7534d" +dependencies = [ + "proc-macro2", + "quote", + "serde_derive_internals", + "syn 2.0.119", +] + +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + +[[package]] +name = "security-framework" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.10.1", + "core-foundation-sys", + "libc", + "security-framework-sys", +] + +[[package]] +name = "security-framework-sys" +version = "2.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "selectors" +version = "0.38.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8adfa1c298912827b8a28b223b3b874357397ae706e6190acd9bf28cee99114d" +dependencies = [ + "bitflags 2.13.2", + "cssparser 0.37.0", + "derive_more", + "log", + "new_debug_unreachable", + "phf 0.13.1", + "phf_codegen 0.13.1", + "precomputed-hash", + "rustc-hash", + "servo_arc 0.4.3", + "smallvec", +] + +[[package]] +name = "selectors" +version = "0.41.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8322aebea94a6cc288ff884e8a49bdbceef60206c400c6c46d22e62fc4fd91a6" +dependencies = [ + "bitflags 2.13.2", + "cssparser 0.38.0", + "derive_more", + "log", + "new_debug_unreachable", + "precomputed-hash", + "rustc-hash", + "servo_arc 0.5.0", + "smallvec", +] + +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" +dependencies = [ + "serde", + "serde_core", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde-untagged" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9faf48a4a2d2693be24c6289dbe26552776eb7737074e6722891fadbe6c5058" +dependencies = [ + "erased-serde", + "serde", + "serde_core", + "typeid", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "serde_derive_internals" +version = "0.29.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_repr" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "serde_spanned" +version = "0.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3" +dependencies = [ + "serde", +] + +[[package]] +name = "serde_spanned" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c187e0a369471c550af028cba56d4f4fa2a489ad28151ae95a4d340a2a8b782" +dependencies = [ + "serde_core", +] + +[[package]] +name = "serde_with" +version = "3.24.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df9adc193c780ef8f159aee8b61e2d5801aaa555e6eb0947fe45530ec506296f" +dependencies = [ + "base64 0.23.1", + "bs58", + "chrono", + "hex", + "indexmap 1.9.3", + "indexmap 2.14.2", + "jiff", + "schemars 0.9.0", + "schemars 1.2.3", + "serde_core", + "serde_json", + "serde_with_macros", + "time", +] + +[[package]] +name = "serde_with_macros" +version = "3.24.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e17bbc68e28663bbbb90df47e058aa7eda4fb445b89fe70457bb94fbccf6e49" +dependencies = [ + "darling", + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "serialize-to-javascript" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "04f3666a07a197cdb77cdf306c32be9b7f598d7060d50cfd4d5aa04bfd92f6c5" +dependencies = [ + "serde", + "serde_json", + "serialize-to-javascript-impl", +] + +[[package]] +name = "serialize-to-javascript-impl" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "772ee033c0916d670af7860b6e1ef7d658a4629a6d0b4c8c3e67f09b3765b75d" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "servo_arc" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "170fb83ab34de17dc69aa7c67482b22218ddb85da56546f9bd6b929e32a05930" +dependencies = [ + "stable_deref_trait", +] + +[[package]] +name = "servo_arc" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4eceb519ec34d8290aaf6e46f435102f2bfa63f22b05a144fb16ab266d3b198" +dependencies = [ + "stable_deref_trait", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "digest 0.10.7", +] + +[[package]] +name = "sha2" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "digest 0.11.3", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "simd-adler32" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea" + +[[package]] +name = "simdutf8" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e" + +[[package]] +name = "siphasher" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "149309498a5f7334b12ddae0cad8aba81ce785fe91755068867e017cf98fee46" + +[[package]] +name = "socket2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "softbuffer" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aac18da81ebbf05109ab275b157c22a653bb3c12cf884450179942f81bcbf6c3" +dependencies = [ + "bytemuck", + "js-sys", + "ndk", + "objc2", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-foundation", + "objc2-quartz-core", + "raw-window-handle", + "redox_syscall", + "tracing", + "wasm-bindgen", + "web-sys", + "windows-sys 0.61.2", +] + +[[package]] +name = "soup3" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "471f924a40f31251afc77450e781cb26d55c0b650842efafc9c6cbd2f7cc4f9f" +dependencies = [ + "futures-channel", + "gio", + "glib", + "libc", + "soup3-sys", +] + +[[package]] +name = "soup3-sys" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ebe8950a680a12f24f15ebe1bf70db7af98ad242d9db43596ad3108aab86c27" +dependencies = [ + "gio-sys", + "glib-sys", + "gobject-sys", + "libc", + "system-deps", +] + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "stackql-workbench" +version = "0.1.0" +dependencies = [ + "apple-native-keyring-store", + "arboard", + "base64 0.23.1", + "futures-util", + "keyring-core", + "reqwest", + "rmcp", + "serde", + "serde_json", + "tauri", + "tauri-build", + "tauri-plugin-dialog", + "tauri-plugin-opener", + "thiserror 2.0.21", + "tokio", + "tokio-postgres", + "windows-native-keyring-store", + "windows-sys 0.61.2", +] + +[[package]] +name = "static_vcruntime" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff7589a1859b09232522bb9edf076ca7fcf14ded96685d3fa629db73023ffbb7" + +[[package]] +name = "string_cache" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a18596f8c785a729f2819c0f6a7eae6ebeebdfffbfe4214ae6b087f690e31901" +dependencies = [ + "new_debug_unreachable", + "parking_lot", + "phf_shared 0.13.1", + "precomputed-hash", +] + +[[package]] +name = "string_cache" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ffa8a5dbe8b3f0bbe29d4c3225daafaeead63afdc1b65fc4c01a1384166038e6" +dependencies = [ + "new_debug_unreachable", + "parking_lot", + "phf_shared 0.14.0", + "precomputed-hash", +] + +[[package]] +name = "string_cache_codegen" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "585635e46db231059f76c5849798146164652513eb9e8ab2685939dd90f29b69" +dependencies = [ + "phf_generator 0.13.1", + "phf_shared 0.13.1", + "proc-macro2", + "quote", +] + +[[package]] +name = "string_cache_codegen" +version = "0.11.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "928dcdf75e47626b3617a976ec205d9f057584c371c1f23b782129268d0e6edc" +dependencies = [ + "phf_generator 0.14.0", + "phf_shared 0.14.0", + "proc-macro2", + "quote", +] + +[[package]] +name = "stringprep" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b4df3d392d81bd458a8a621b8bffbd2302a12ffe288a9d931670948749463b1" +dependencies = [ + "unicode-bidi", + "unicode-normalization", + "unicode-properties", +] + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + +[[package]] +name = "swift-rs" +version = "1.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cefd87076fd385308ee4aff597256c902f1fbb4d031de1558efc12f8ffefadd9" +dependencies = [ + "base64 0.21.7", + "serde", + "serde_json", +] + +[[package]] +name = "syn" +version = "1.0.109" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237" +dependencies = [ + "proc-macro2", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sync_wrapper" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" +dependencies = [ + "futures-core", +] + +[[package]] +name = "synstructure" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "system-configuration" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.9.4", + "system-configuration-sys", +] + +[[package]] +name = "system-configuration-sys" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "system-deps" +version = "6.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a3e535eb8dded36d55ec13eddacd30dec501792ff23a0b1682c38601b8cf2349" +dependencies = [ + "cfg-expr", + "heck 0.5.0", + "pkg-config", + "toml 0.8.2", + "version-compare", +] + +[[package]] +name = "tao" +version = "0.37.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d5777b06fe6435126ae8d816eba269e050e1e10d302cf5461e9c49eccabc3548" +dependencies = [ + "bitflags 2.13.2", + "block2", + "core-foundation 0.10.1", + "core-graphics", + "crossbeam-channel", + "dbus", + "dispatch2", + "dlopen2", + "dpi", + "gdkwayland-sys", + "gdkx11-sys", + "gtk", + "jni", + "libc", + "log", + "ndk", + "ndk-context", + "ndk-sys", + "objc2", + "objc2-app-kit", + "objc2-foundation", + "objc2-ui-kit", + "parking_lot", + "percent-encoding", + "raw-window-handle", + "tao-macros", + "unicode-segmentation", + "url", + "windows", + "windows-core", + "windows-version", + "x11-dl", +] + +[[package]] +name = "tao-macros" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5f7eeb6d99155545da6150a1795945f16ac9c178deb2a5f2e74d776107bd5849" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "target-lexicon" +version = "0.12.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1" + +[[package]] +name = "tauri" +version = "2.12.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c2a5cad3827d1fa46c206a6bcaee8ca14203e9b0aaabe447dd4acef33ecd065" +dependencies = [ + "anyhow", + "bytes", + "cookie", + "dirs", + "dunce", + "embed_plist", + "getrandom 0.3.4", + "glob", + "gtk", + "heck 0.5.0", + "http", + "jni", + "libc", + "log", + "mime", + "muda", + "objc2", + "objc2-app-kit", + "objc2-foundation", + "objc2-ui-kit", + "objc2-web-kit", + "percent-encoding", + "plist", + "raw-window-handle", + "reqwest", + "serde", + "serde_json", + "serde_repr", + "serialize-to-javascript", + "swift-rs", + "tauri-build", + "tauri-macros", + "tauri-runtime", + "tauri-runtime-wry", + "tauri-utils", + "thiserror 2.0.21", + "tokio", + "tray-icon", + "url", + "webkit2gtk", + "webview2-com", + "window-vibrancy", + "windows", +] + +[[package]] +name = "tauri-build" +version = "2.7.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e03658bfc9cb60f96a05b7d07a7f7cdfbf4c30b1bbfcb5cf6b5342cc2c9e0bc" +dependencies = [ + "anyhow", + "cargo_toml", + "dirs", + "glob", + "heck 0.5.0", + "json-patch", + "schemars 0.8.22", + "semver", + "serde", + "serde_json", + "static_vcruntime", + "strsim", + "tauri-utils", + "tauri-winres", + "walkdir", +] + +[[package]] +name = "tauri-codegen" +version = "2.7.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c454a15120b885bf57d0cb9ab218c01e12bc672f793452cb6527b460db883aa" +dependencies = [ + "base64 0.23.1", + "brotli", + "ico", + "json-patch", + "plist", + "png", + "proc-macro2", + "quote", + "semver", + "serde", + "serde_json", + "sha2 0.11.1", + "syn 2.0.119", + "tauri-utils", + "thiserror 2.0.21", + "time", + "url", + "uuid", + "walkdir", +] + +[[package]] +name = "tauri-macros" +version = "2.7.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8f7513896f637528ec27ff76effd90638b1cdfa77499fae3db078043aed7ecb" +dependencies = [ + "heck 0.5.0", + "proc-macro2", + "quote", + "syn 2.0.119", + "tauri-codegen", + "tauri-utils", +] + +[[package]] +name = "tauri-plugin" +version = "2.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "51bf2a10dc09e68324a8227b3ec785bd8b61872ddb978c3447b07bc7dd180b25" +dependencies = [ + "anyhow", + "glob", + "plist", + "schemars 0.8.22", + "serde", + "serde_json", + "tauri-utils", + "walkdir", +] + +[[package]] +name = "tauri-plugin-dialog" +version = "2.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce0fb9c2b6d34a9720627ed930ebc8af26f61e648695aecaeb03d5c33c5896f5" +dependencies = [ + "log", + "raw-window-handle", + "rfd", + "serde", + "serde_json", + "tauri", + "tauri-plugin", + "tauri-plugin-fs", + "thiserror 2.0.21", + "url", +] + +[[package]] +name = "tauri-plugin-fs" +version = "2.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d58eb1d4984e535f47a642ffec09a2da6f5c18a12b5902d12126cb7626d628b" +dependencies = [ + "anyhow", + "dunce", + "glob", + "log", + "objc2-foundation", + "percent-encoding", + "schemars 0.8.22", + "serde", + "serde_json", + "serde_repr", + "tauri", + "tauri-plugin", + "tauri-utils", + "thiserror 2.0.21", + "toml 1.2.1+spec-1.1.0", + "url", +] + +[[package]] +name = "tauri-plugin-opener" +version = "2.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "54592c6718b42ab198bf11bda6a428a3553ca2f2f8e506df56f6a063ec328331" +dependencies = [ + "dunce", + "glob", + "objc2-app-kit", + "objc2-foundation", + "open", + "schemars 0.8.22", + "serde", + "serde_json", + "tauri", + "tauri-plugin", + "thiserror 2.0.21", + "url", + "windows", + "zbus", +] + +[[package]] +name = "tauri-runtime" +version = "2.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c4b2a71c4bf51cde5cdcf1b45d7943282c7c669d3d26f7a324cce25f1b53e75" +dependencies = [ + "cookie", + "dpi", + "gtk", + "http", + "jni", + "objc2", + "objc2-ui-kit", + "objc2-web-kit", + "raw-window-handle", + "serde", + "serde_json", + "tauri-utils", + "thiserror 2.0.21", + "url", + "webkit2gtk", + "webview2-com", + "windows", +] + +[[package]] +name = "tauri-runtime-wry" +version = "2.12.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d9be5e7af9560a4a60cdd441389a066cdd3e7c5d464a006ae34cb276cc78abd" +dependencies = [ + "gtk", + "http", + "jni", + "log", + "objc2", + "objc2-app-kit", + "percent-encoding", + "raw-window-handle", + "softbuffer", + "tao", + "tauri-runtime", + "tauri-utils", + "url", + "webkit2gtk", + "webview2-com", + "windows", + "wry", +] + +[[package]] +name = "tauri-utils" +version = "2.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6bf649f12d6fb11e1867214973cd37d89786ae2c0904f79b787b1db4fdcd14c" +dependencies = [ + "anyhow", + "brotli", + "cargo_metadata", + "ctor", + "dom_query 0.28.0", + "dunce", + "glob", + "http", + "infer", + "json-patch", + "log", + "memchr", + "phf 0.13.1", + "plist", + "proc-macro2", + "quote", + "regex", + "schemars 0.8.22", + "semver", + "serde", + "serde-untagged", + "serde_json", + "serde_with", + "swift-rs", + "thiserror 2.0.21", + "toml 1.2.1+spec-1.1.0", + "url", + "urlpattern", + "uuid", + "walkdir", +] + +[[package]] +name = "tauri-winres" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c52bb6904475a6ca662f15ef787f18ade61d5740a1ee12c45d3b748efdb6f796" +dependencies = [ + "dunce", + "embed-resource", + "toml 1.2.1+spec-1.1.0", +] + +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom 0.4.3", + "once_cell", + "rustix", + "windows-sys 0.61.2", +] + +[[package]] +name = "tendril" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5fed54709c5b3a53d09bb1c113ea4f5ceafd1e772ddcb0030a82e1d56c087b08" +dependencies = [ + "new_debug_unreachable", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl 1.0.69", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl 2.0.21", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "time" +version = "0.3.55" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdb87b95ec50ddfa440816d227a17b2ccbdda963a316a727fda0fc4334f7d134" +dependencies = [ + "deranged", + "num-conv", + "powerfmt", + "serde_core", + "time-core", + "time-macros", +] + +[[package]] +name = "time-core" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109" + +[[package]] +name = "time-macros" +version = "0.2.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85" +dependencies = [ + "num-conv", + "time-core", +] + +[[package]] +name = "tinystr" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abc840c238154d58f9e86b2792261edfde565a17696e1cda1a449de27979801a" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "tinyvec" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee" + +[[package]] +name = "tokio" +version = "1.54.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3" +dependencies = [ + "bytes", + "libc", + "mio", + "pin-project-lite", + "signal-hook-registry", + "socket2", + "tokio-macros", + "windows-sys 0.61.2", +] + +[[package]] +name = "tokio-macros" +version = "2.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "tokio-native-tls" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2" +dependencies = [ + "native-tls", + "tokio", +] + +[[package]] +name = "tokio-postgres" +version = "0.7.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a528f7d280f6d5b9cd149635c8705b0dd049754bc67d81d31fa25169a93809d3" +dependencies = [ + "async-trait", + "byteorder", + "bytes", + "fallible-iterator", + "futures-channel", + "futures-util", + "log", + "parking_lot", + "percent-encoding", + "phf 0.13.1", + "pin-project-lite", + "postgres-protocol", + "postgres-types", + "rand", + "socket2", + "tokio", + "tokio-util", + "whoami", +] + +[[package]] +name = "tokio-rustls" +version = "0.26.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c9cc2678c2cdd569ef8215e2afd7954ada2ae20b4fdd2c5fe6139a3b02d105db" +dependencies = [ + "rustls", + "tokio", +] + +[[package]] +name = "tokio-stream" +version = "0.1.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b" +dependencies = [ + "futures-core", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "tokio-util" +version = "0.7.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b" +dependencies = [ + "bytes", + "futures-core", + "futures-sink", + "libc", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "toml" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "185d8ab0dfbb35cf1399a6344d8484209c088f75f8f68230da55d48d95d43e3d" +dependencies = [ + "serde", + "serde_spanned 0.6.9", + "toml_datetime 0.6.3", + "toml_edit 0.20.2", +] + +[[package]] +name = "toml" +version = "1.2.1+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d5755c51863cdac711f1956baf8eb9588e060755f7d3c4c979e70ea1e1f32cd7" +dependencies = [ + "indexmap 2.14.2", + "serde_core", + "serde_spanned 1.1.3", + "toml_datetime 1.1.3+spec-1.1.0", + "toml_parser", + "toml_writer", + "winnow 1.0.5", +] + +[[package]] +name = "toml_datetime" +version = "0.6.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7cda73e2f1397b1262d6dfdcef8aafae14d1de7748d66822d3bfeeb6d03e5e4b" +dependencies = [ + "serde", +] + +[[package]] +name = "toml_datetime" +version = "1.1.3+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "173f25c883cd2176a2d8212155638c0a60d484a9d84546d270866f40f56b6e49" +dependencies = [ + "serde_core", +] + +[[package]] +name = "toml_edit" +version = "0.19.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b5bb770da30e5cbfde35a2d7b9b8a2c4b8ef89548a7a6aeab5c9a576e3e7421" +dependencies = [ + "indexmap 2.14.2", + "toml_datetime 0.6.3", + "winnow 0.5.40", +] + +[[package]] +name = "toml_edit" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "396e4d48bbb2b7554c944bde63101b5ae446cff6ec4a24227428f15eb72ef338" +dependencies = [ + "indexmap 2.14.2", + "serde", + "serde_spanned 0.6.9", + "toml_datetime 0.6.3", + "winnow 0.5.40", +] + +[[package]] +name = "toml_edit" +version = "0.25.19+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dd43688c4858d7264ae1cf9a9f874a67c3feb74a883b1cd7bebd6a4ea8307218" +dependencies = [ + "indexmap 2.14.2", + "toml_datetime 1.1.3+spec-1.1.0", + "toml_parser", + "winnow 1.0.5", +] + +[[package]] +name = "toml_parser" +version = "1.1.5+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c" +dependencies = [ + "winnow 1.0.5", +] + +[[package]] +name = "toml_writer" +version = "1.2.0+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "009dbb7700f11c55ef83aebbe4c0e9cf1f1ac0844bd8d6f00dc38f302026e13a" + +[[package]] +name = "tower" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4" +dependencies = [ + "futures-core", + "futures-util", + "pin-project-lite", + "sync_wrapper", + "tokio", + "tower-layer", + "tower-service", +] + +[[package]] +name = "tower-http" +version = "0.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840" +dependencies = [ + "bitflags 2.13.2", + "bytes", + "futures-util", + "http", + "http-body", + "pin-project-lite", + "tower", + "tower-layer", + "tower-service", + "url", +] + +[[package]] +name = "tower-layer" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-attributes", + "tracing-core", +] + +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", +] + +[[package]] +name = "tray-icon" +version = "0.25.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2b9c52859a94554803ccd4a24b98f74148ebc73b90676d783f3490b1bff9d72" +dependencies = [ + "crossbeam-channel", + "dirs", + "libappindicator", + "muda", + "objc2", + "objc2-app-kit", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-foundation", + "once_cell", + "png", + "serde", + "thiserror 2.0.21", + "windows-sys 0.61.2", +] + +[[package]] +name = "try-lock" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" + +[[package]] +name = "typeid" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bc7d623258602320d5c55d1bc22793b57daff0ec7efc270ea7d55ce1d5f5471c" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "uds_windows" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e" +dependencies = [ + "memoffset", + "tempfile", + "windows-sys 0.61.2", +] + +[[package]] +name = "unicode-bidi" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5" + +[[package]] +name = "unicode-general-category" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b993bddc193ae5bd0d623b49ec06ac3e9312875fdae725a975c51db1cc1677f" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "unicode-normalization" +version = "0.1.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75cd3fb03d5288b3ba9a1ee103ac7e9cbb59f0b03d64f8ddfcc04dd42758a85d" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "unicode-properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "993ad287eb20e8ba755312801cfe1413e0f25d604075863acaddca10b04c1833" + +[[package]] +name = "unicode-segmentation" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8" + +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", + "serde_derive", +] + +[[package]] +name = "urlpattern" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df16f50ef4cc145211879a3867ba757076b25dfee812040dcb0658bd9ae7904b" +dependencies = [ + "icu_properties", + "regex", + "serde", + "url", +] + +[[package]] +name = "utf8_iter" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af3bd9d3e571c26fcce9d033b87ea5ab061b8d2ffe9b7a5675d810d68f03edf0" +dependencies = [ + "utf_types", +] + +[[package]] +name = "utf_types" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a3b425286980a367278453f3b6d28cdcb134b574e5a35824a6ff5eebad50bb6" + +[[package]] +name = "uuid" +version = "1.29.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c14b15dffa2f4bd712103e857140aa04a4f2ff6e955c77d7eb8e53ee02a3b64" +dependencies = [ + "getrandom 0.4.3", + "js-sys", + "serde_core", + "wasm-bindgen", +] + +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "version-compare" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03c2856837ef78f57382f06b2b8563a2f512f7185d732608fd9176cb3b8edf0e" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "vswhom" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be979b7f07507105799e854203b470ff7c78a1639e330a58f183b5fea574608b" +dependencies = [ + "libc", + "vswhom-sys", +] + +[[package]] +name = "vswhom-sys" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fb067e4cbd1ff067d1df46c9194b5de0e98efd2810bbc95c5d5e5f25a3231150" +dependencies = [ + "cc", + "libc", +] + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "want" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b" +dependencies = [ + "try-lock", +] + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasi" +version = "0.14.7+wasi-0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "883478de20367e224c0090af9cf5f9fa85bed63a95c1abf3afc5c083ebc06e8c" +dependencies = [ + "wasip2", +] + +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "wasite" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "66fe902b4a6b8028a753d5424909b764ccf79b7a209eac9bf97e59cda9f71a42" +dependencies = [ + "wasi 0.14.7+wasi-0.2.4", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c" +dependencies = [ + "cfg-if", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-futures" +version = "0.4.80" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e14e0327cb5368ad60ccb22d04a9827a693c95a926d8d125e9fa39e0baec501" +dependencies = [ + "js-sys", + "tokio", + "wasm-bindgen", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.10", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "wasm-streams" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb" +dependencies = [ + "futures-util", + "js-sys", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + +[[package]] +name = "web-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7d179596ff5ec0f6de4db64d54011bde6289cc49603d3a6e4ce3f329207ab88" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "web_atoms" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba8b815c1b593dc0baf78dd0f4fc8fdb2de53198fb1163738093e9a311c33fb3" +dependencies = [ + "phf 0.13.1", + "phf_codegen 0.13.1", + "string_cache 0.9.0", + "string_cache_codegen 0.6.1", +] + +[[package]] +name = "web_atoms" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7572660c8890448ba236b7376f27e389c6a7e1c70195622faced601f855c0ada" +dependencies = [ + "phf 0.14.0", + "phf_codegen 0.14.0", + "string_cache 0.11.0", + "string_cache_codegen 0.11.2", +] + +[[package]] +name = "webkit2gtk" +version = "2.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1027150013530fb2eaf806408df88461ae4815a45c541c8975e61d6f2fc4793" +dependencies = [ + "bitflags 1.3.2", + "cairo-rs", + "gdk", + "gdk-sys", + "gio", + "gio-sys", + "glib", + "glib-sys", + "gobject-sys", + "gtk", + "gtk-sys", + "javascriptcore-rs", + "libc", + "once_cell", + "soup3", + "webkit2gtk-sys", +] + +[[package]] +name = "webkit2gtk-sys" +version = "2.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "916a5f65c2ef0dfe12fff695960a2ec3d4565359fdbb2e9943c974e06c734ea5" +dependencies = [ + "bitflags 1.3.2", + "cairo-sys-rs", + "gdk-sys", + "gio-sys", + "glib-sys", + "gobject-sys", + "gtk-sys", + "javascriptcore-rs-sys", + "libc", + "pkg-config", + "soup3-sys", + "system-deps", +] + +[[package]] +name = "webview2-com" +version = "0.39.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f89fca7a704cee10dcb3654c1dbb8941d1783132f1917358af75bec37a7d7e6" +dependencies = [ + "webview2-com-macros", + "webview2-com-sys", + "windows", + "windows-core", +] + +[[package]] +name = "webview2-com-macros" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67a921c1b6914c367b2b823cd4cde6f96beec77d30a939c8199bb377cf9b9b54" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "webview2-com-sys" +version = "0.39.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b3a07132775117d6065853d9d1178157b8c90e228de47129d6bce2c7edebedfb" +dependencies = [ + "thiserror 2.0.21", + "windows", + "windows-core", +] + +[[package]] +name = "whoami" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "626c4bac6755d76ffc12cb01b2eac751db1996b9e0041de9aa02c8c211ddc82c" +dependencies = [ + "libc", + "libredox", + "objc2-system-configuration", + "wasite", + "web-sys", +] + +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" + +[[package]] +name = "window-vibrancy" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "111e51caca442cafd9bab396628ac4d814880eaea4e63dfd76a12e9f342b5580" +dependencies = [ + "objc2", + "objc2-app-kit", + "objc2-core-foundation", + "objc2-foundation", + "objc2-quartz-core", + "raw-window-handle", + "windows-sys 0.61.2", + "windows-version", +] + +[[package]] +name = "windows" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580" +dependencies = [ + "windows-collections", + "windows-core", + "windows-future", + "windows-numerics", +] + +[[package]] +name = "windows-collections" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610" +dependencies = [ + "windows-core", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-future" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb" +dependencies = [ + "windows-core", + "windows-link", + "windows-threading", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-native-keyring-store" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "063426e76fdec7438d56bb777f67e318a84a25c707b07e575cb8b78e10c028f8" +dependencies = [ + "byteorder", + "keyring-core", + "regex", + "windows-sys 0.61.2", + "zeroize", +] + +[[package]] +name = "windows-numerics" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26" +dependencies = [ + "windows-core", + "windows-link", +] + +[[package]] +name = "windows-registry" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720" +dependencies = [ + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-sys" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0" +dependencies = [ + "windows-targets 0.42.2", +] + +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets 0.52.6", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-targets" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e5180c00cd44c9b1c88adb3693291f1cd93605ded80c250a75d472756b4d071" +dependencies = [ + "windows_aarch64_gnullvm 0.42.2", + "windows_aarch64_msvc 0.42.2", + "windows_i686_gnu 0.42.2", + "windows_i686_msvc 0.42.2", + "windows_x86_64_gnu 0.42.2", + "windows_x86_64_gnullvm 0.42.2", + "windows_x86_64_msvc 0.42.2", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm 0.52.6", + "windows_aarch64_msvc 0.52.6", + "windows_i686_gnu 0.52.6", + "windows_i686_gnullvm", + "windows_i686_msvc 0.52.6", + "windows_x86_64_gnu 0.52.6", + "windows_x86_64_gnullvm 0.52.6", + "windows_x86_64_msvc 0.52.6", +] + +[[package]] +name = "windows-threading" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-version" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4060a1da109b9d0326b7262c8e12c84df67cc0dbc9e33cf49e01ccc2eb63631" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8" + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "winnow" +version = "0.5.40" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f593a95398737aeed53e489c785df13f3618e41dbcd6718c6addbf1395aa6876" +dependencies = [ + "memchr", +] + +[[package]] +name = "winnow" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c3b93199df0ab874cdf0c6a94f0a0dc3423fe41f1cafb62b8bd7b1deb277aef" +dependencies = [ + "memchr", +] + +[[package]] +name = "winreg" +version = "0.56.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7d6f32a0ff4a9f6f01231eb2059cc85479330739333e0e58cadf03b6af2cca10" +dependencies = [ + "cfg-if", + "windows-sys 0.61.2", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "writeable" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" + +[[package]] +name = "wry" +version = "0.57.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a490119196d02a51d0871df7b9119a1f3e46d75b7e90053a801454d5c6b3491c" +dependencies = [ + "base64 0.23.1", + "block2", + "cookie", + "crossbeam-channel", + "dirs", + "dom_query 0.29.0", + "dpi", + "dunce", + "gdkx11", + "gtk", + "http", + "javascriptcore-rs", + "jni", + "libc", + "ndk", + "objc2", + "objc2-app-kit", + "objc2-core-foundation", + "objc2-foundation", + "objc2-ui-kit", + "objc2-web-kit", + "percent-encoding", + "raw-window-handle", + "sha2 0.10.9", + "soup3", + "tao-macros", + "thiserror 2.0.21", + "url", + "webkit2gtk", + "webkit2gtk-sys", + "webview2-com", + "windows", + "windows-core", + "windows-version", + "x11-dl", +] + +[[package]] +name = "x11" +version = "2.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "502da5464ccd04011667b11c435cb992822c2c0dbde1770c988480d312a0db2e" +dependencies = [ + "libc", + "pkg-config", +] + +[[package]] +name = "x11-dl" +version = "2.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38735924fedd5314a6e548792904ed8c6de6636285cb9fec04d5b1db85c1516f" +dependencies = [ + "libc", + "once_cell", + "pkg-config", +] + +[[package]] +name = "x11rb" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414" +dependencies = [ + "gethostname", + "rustix", + "x11rb-protocol", +] + +[[package]] +name = "x11rb-protocol" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd" + +[[package]] +name = "yoke" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "417ef3fcf6c300b7dbd25c85531a746931c02ad536f3cf4786ed1e88223340b3" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", + "synstructure", +] + +[[package]] +name = "zbus" +version = "5.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907" +dependencies = [ + "async-broadcast", + "async-executor", + "async-io", + "async-lock", + "async-process", + "async-recursion", + "async-task", + "async-trait", + "blocking", + "enumflags2", + "event-listener", + "futures-core", + "futures-lite", + "hex", + "libc", + "ordered-stream", + "rustix", + "serde", + "serde_repr", + "tracing", + "uds_windows", + "uuid", + "windows-sys 0.61.2", + "winnow 1.0.5", + "zbus_macros", + "zbus_names", + "zvariant", +] + +[[package]] +name = "zbus_macros" +version = "5.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40" +dependencies = [ + "proc-macro-crate 3.5.0", + "proc-macro2", + "quote", + "syn 3.0.10", + "zbus_names", + "zvariant", + "zvariant_utils", +] + +[[package]] +name = "zbus_names" +version = "4.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "812a12be4ead7a59e18ea8f047d08add0066b73bc62fc1467066a2472ae088dd" +dependencies = [ + "serde", + "winnow 1.0.5", + "zvariant", +] + +[[package]] +name = "zcheapstr" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "939f186d9ecebe044315a5cb6d6f78568bbc21152adc954d5a0c2f58bdbc9920" +dependencies = [ + "serde", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", + "synstructure", +] + +[[package]] +name = "zeroize" +version = "1.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879" + +[[package]] +name = "zerotrie" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f58a2799cfe9a1670c7ea8edbd52ef8edb93cb37a7f83bf31ba9e35d9dae6a40" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "zlib-rs" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" + +[[package]] +name = "zvariant" +version = "5.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "80bf6d6cd6a4b601acb64cfb8284cdc643fcfa75ef26ae3c46ec8aa4e8a1fbb7" +dependencies = [ + "endi", + "enumflags2", + "serde", + "winnow 1.0.5", + "zcheapstr", + "zvariant_derive", + "zvariant_utils", +] + +[[package]] +name = "zvariant_derive" +version = "5.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef2672456ba1cb54b5eaec136e63135b3c7495fb938e53b28a62e633496d486d" +dependencies = [ + "proc-macro-crate 3.5.0", + "proc-macro2", + "quote", + "syn 3.0.10", + "zvariant_utils", +] + +[[package]] +name = "zvariant_utils" +version = "4.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3" +dependencies = [ + "proc-macro2", + "quote", + "serde", + "syn 3.0.10", + "winnow 1.0.5", +] diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml new file mode 100644 index 0000000..a18d007 --- /dev/null +++ b/src-tauri/Cargo.toml @@ -0,0 +1,90 @@ +[package] +name = "stackql-workbench" +version = "0.1.0" +description = "Desktop query IDE and chat interface for StackQL" +edition = "2024" +rust-version = "1.90" +license = "MIT" +repository = "https://github.com/stackql/stackql-workbench" +publish = false + +[lib] +# The lib name must differ from the bin name, see rust-lang/cargo#8519. +name = "stackql_workbench_lib" + +[[bin]] +name = "stackql-workbench" +path = "src/main.rs" + +[build-dependencies] +tauri-build = { version = "2", features = [] } + +[dependencies] +tauri = { version = "2", features = [] } +serde = { version = "1", features = ["derive"] } +serde_json = "1" +thiserror = "2" +tokio = { version = "1", features = [ + "process", + "io-util", + "net", + "time", + "sync", + "rt", + "rt-multi-thread", + "macros", +] } +tokio-postgres = "0.7" +futures-util = "0.3" +# Text only. The default feature adds image support, which is not used. +arboard = { version = "3", default-features = false } +# HTTPS client. native-tls uses the TLS stack and trust store of the OS, which +# avoids the extra build tools the default rustls provider needs on Windows. +reqwest = { version = "0.13", default-features = false, features = [ + "native-tls", + "http2", + "system-proxy", + "json", + "charset", +] } +base64 = "0.23" +# The official Rust MCP SDK, client side only, over a stdio pair the host owns. +rmcp = { version = "3", default-features = false, features = ["client", "transport-async-rw"] } +# OS keychain access. keyring-core is the API; the platform stores are below. +keyring-core = "1" +# The system save dialog for exports. Called from host commands only. +tauri-plugin-dialog = "2" +# Opens the app's own links in the default browser. Called from a host command only. +tauri-plugin-opener = "2" + +[target.'cfg(windows)'.dependencies] +windows-sys = { version = "0.61", features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_JobObjects", + # The dialog shown when no WebView2 runtime is found. The second is needed + # for the first to define it. + "Win32_UI_Controls", + "Win32_UI_WindowsAndMessaging", +] } +windows-native-keyring-store = "1" + +[target.'cfg(windows)'.dev-dependencies] +# The supervisor's tests open a handle to a child and wait on it to see it end. +windows-sys = { version = "0.61", features = ["Win32_System_Threading"] } + +[target.'cfg(target_os = "macos")'.dependencies] +apple-native-keyring-store = { version = "1", features = ["keychain"] } + +[lints.rust] +unsafe_op_in_unsafe_fn = "deny" + +[lints.clippy] +unwrap_used = "deny" +expect_used = "deny" + +[profile.release] +codegen-units = 1 +lto = true +opt-level = 3 +strip = true diff --git a/src-tauri/build.rs b/src-tauri/build.rs new file mode 100644 index 0000000..261851f --- /dev/null +++ b/src-tauri/build.rs @@ -0,0 +1,3 @@ +fn main() { + tauri_build::build(); +} diff --git a/src-tauri/capabilities/default.json b/src-tauri/capabilities/default.json new file mode 100644 index 0000000..8fe1fec --- /dev/null +++ b/src-tauri/capabilities/default.json @@ -0,0 +1,7 @@ +{ + "$schema": "../gen/schemas/desktop-schema.json", + "identifier": "default", + "description": "Capability for the main window. The app's own commands need no entry here.", + "windows": ["main"], + "permissions": ["core:default", "core:window:allow-close"] +} diff --git a/src-tauri/clippy.toml b/src-tauri/clippy.toml new file mode 100644 index 0000000..0358cdb --- /dev/null +++ b/src-tauri/clippy.toml @@ -0,0 +1,2 @@ +allow-unwrap-in-tests = true +allow-expect-in-tests = true diff --git a/src-tauri/examples/mcp_spike.rs b/src-tauri/examples/mcp_spike.rs new file mode 100644 index 0000000..4c22781 --- /dev/null +++ b/src-tauri/examples/mcp_spike.rs @@ -0,0 +1,509 @@ +//! MCP spike against a real `stackql mcp` over stdio. +//! +//! Starts the engine's MCP server as a child process, connects with `rmcp` +//! the way the host does (the host owns the process and hands the SDK the +//! pipes), and records what the agent runtime depends on: protocol revision +//! negotiation, the tool list, result shapes, how a mutation asks for +//! approval, and what lands in the audit log. The output is the evidence in +//! `docs/spike-mcp.md`. +//! +//! Run from `src-tauri`: +//! +//! ```text +//! cargo run --example mcp_spike -- [--bin ] [--approot ] +//! ``` +//! +//! No cloud credentials are used. The only mutation that is approved is +//! against a provider with no credentials configured, so it cannot succeed. + +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use std::path::{Path, PathBuf}; +use std::process::Stdio; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use rmcp::model::{ + CallToolRequestParams, CallToolResult, ClientCapabilities, ClientConfig, ElicitRequestParams, + ElicitResult, ElicitationAction, ElicitationCapability, FormElicitationCapability, + Implementation, ProtocolVersion, +}; +use rmcp::service::{RequestContext, RoleClient, RunningService}; +use rmcp::{ClientHandler, ErrorData, ServiceExt}; +use tokio::io::{AsyncBufReadExt, BufReader}; +use tokio::process::{Child, Command}; + +type AnyError = Box; + +/// What the stand-in for the operator answers when asked to approve. +#[derive(Clone, Copy, Debug)] +enum Answer { + Accept, + Decline, + Cancel, +} + +#[derive(Clone)] +struct SpikeClient { + version: ProtocolVersion, + advertise_elicitation: bool, + answer: Arc>, + seen: Arc>>, +} + +impl ClientHandler for SpikeClient { + fn get_info(&self) -> ClientConfig { + let mut capabilities = ClientCapabilities::default(); + if self.advertise_elicitation { + let mut elicitation = ElicitationCapability::default(); + elicitation.form = Some(FormElicitationCapability::default()); + capabilities.elicitation = Some(elicitation); + } + ClientConfig::new( + capabilities, + Implementation::new("stackql-workbench-spike", env!("CARGO_PKG_VERSION")), + ) + .with_protocol_version(self.version.clone()) + } + + async fn create_elicitation( + &self, + request: ElicitRequestParams, + _context: RequestContext, + ) -> Result { + let json = serde_json::to_string_pretty(&request).unwrap_or_default(); + self.seen.lock().unwrap().push(json); + let answer = *self.answer.lock().unwrap(); + Ok(match answer { + Answer::Accept => { + ElicitResult::new(ElicitationAction::Accept).with_content(serde_json::json!({})) + } + Answer::Decline => ElicitResult::new(ElicitationAction::Decline), + Answer::Cancel => ElicitResult::new(ElicitationAction::Cancel), + }) + } +} + +struct Session { + child: Child, + service: RunningService, + answer: Arc>, + seen: Arc>>, + stderr: Arc>>, + connect_ms: u128, +} + +async fn connect( + bin: &Path, + approot: &Path, + audit_dir: &Path, + mode: &str, + version: ProtocolVersion, + advertise_elicitation: bool, +) -> Result { + let config = serde_json::json!({ + "server": { + "transport": "stdio", + "mode": mode, + "audit": { "format": "jsonl", "file": { "dir": audit_dir } } + } + }); + let started = Instant::now(); + let mut child = Command::new(bin) + .arg("mcp") + .arg("--mcp.server.type=stdio") + .arg("--approot") + .arg(approot) + .arg("--mcp.config") + .arg(config.to_string()) + .current_dir(approot) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .kill_on_drop(true) + .spawn()?; + let stdin = child.stdin.take().ok_or("no stdin")?; + let stdout = child.stdout.take().ok_or("no stdout")?; + let stderr: Arc>> = Arc::default(); + if let Some(pipe) = child.stderr.take() { + let sink = stderr.clone(); + tokio::spawn(async move { + let mut lines = BufReader::new(pipe).lines(); + while let Ok(Some(line)) = lines.next_line().await { + sink.lock().unwrap().push(line); + } + }); + } + + let answer = Arc::new(Mutex::new(Answer::Decline)); + let seen: Arc>> = Arc::default(); + let client = SpikeClient { + version, + advertise_elicitation, + answer: answer.clone(), + seen: seen.clone(), + }; + // The host owns the process. The SDK only gets the two pipes. + let service = client.serve((stdout, stdin)).await?; + Ok(Session { + child, + service, + answer, + seen, + stderr, + connect_ms: started.elapsed().as_millis(), + }) +} + +fn clip(text: &str, max: usize) -> String { + let flat = text.replace(['\r', '\n'], " | "); + if flat.chars().count() > max { + let head: String = flat.chars().take(max).collect(); + format!("{head}... [{} chars]", flat.chars().count()) + } else { + flat + } +} + +fn describe(result: &CallToolResult) -> String { + let text: Vec = result + .content + .iter() + .filter_map(|block| block.as_text().map(|t| t.text.clone())) + .collect(); + let structured = result + .structured_content + .as_ref() + .map_or_else(|| "none".to_string(), |v| clip(&v.to_string(), 420)); + format!( + "is_error={:?} content_blocks={} text={:?}\n structured={structured}", + result.is_error, + result.content.len(), + clip(&text.join("\n"), 320), + ) +} + +async fn call(session: &Session, tool: &str, args: serde_json::Value) { + let started = Instant::now(); + let mut params = CallToolRequestParams::new(tool.to_string()); + if let Some(object) = args.as_object() { + params = params.with_arguments(object.clone()); + } + let outcome = + tokio::time::timeout(Duration::from_secs(60), session.service.call_tool(params)).await; + let ms = started.elapsed().as_millis(); + println!("\n> {tool} {}", clip(&args.to_string(), 200)); + match outcome { + Ok(Ok(result)) => println!(" [{ms} ms] {}", describe(&result)), + Ok(Err(err)) => println!(" [{ms} ms] protocol error: {err}"), + Err(_) => println!(" [{ms} ms] timed out"), + } + let mut seen = session.seen.lock().unwrap(); + for request in seen.drain(..) { + println!(" elicitation request received:"); + for line in request.lines() { + println!(" {line}"); + } + } +} + +async fn close(mut session: Session) { + let reason = session.service.cancel().await; + println!("\nclient closed: {reason:?}"); + let exit = tokio::time::timeout(Duration::from_secs(5), session.child.wait()).await; + println!("server process after its stdin closed: {exit:?}"); + let _ = session.child.kill().await; +} + +fn print_audit(dir: &Path) { + println!("\n== audit log =="); + let Ok(entries) = std::fs::read_dir(dir) else { + println!("no audit directory at {}", dir.display()); + return; + }; + let mut files: Vec = entries.flatten().map(|e| e.path()).collect(); + files.sort(); + for file in &files { + let text = std::fs::read_to_string(file).unwrap_or_default(); + println!( + "{} ({} lines)", + file.file_name().unwrap_or_default().to_string_lossy(), + text.lines().count() + ); + } + if let Some(last) = files.last() { + let text = std::fs::read_to_string(last).unwrap_or_default(); + println!("last file, every record:"); + for line in text.lines() { + println!(" {}", clip(line, 400)); + } + } +} + +#[tokio::main] +async fn main() -> Result<(), AnyError> { + let mut bin = + std::env::var_os("STACKQL_BIN").map_or_else(|| PathBuf::from("stackql"), PathBuf::from); + let mut approot = std::env::temp_dir().join("stackql-workbench-spike"); + let mut args = std::env::args().skip(1); + while let Some(arg) = args.next() { + match arg.as_str() { + "--bin" => bin = PathBuf::from(args.next().ok_or("--bin needs a value")?), + "--approot" => approot = PathBuf::from(args.next().ok_or("--approot needs a value")?), + other => return Err(format!("unknown argument {other}").into()), + } + } + std::fs::create_dir_all(&approot)?; + let audit_dir = approot.join("audit-spike"); + let _ = std::fs::remove_dir_all(&audit_dir); + std::fs::create_dir_all(&audit_dir)?; + + let version = Command::new(&bin).arg("--version").output().await?; + println!( + "engine: {}", + String::from_utf8_lossy(&version.stdout) + .lines() + .next() + .unwrap_or("") + ); + println!("rmcp: 3.11"); + + println!("\n== protocol revision negotiation =="); + for offered in [ + ProtocolVersion::V_2024_11_05, + ProtocolVersion::V_2025_06_18, + ProtocolVersion::LATEST_WITH_INITIALIZE, + ProtocolVersion::LATEST, + ] { + match tokio::time::timeout( + Duration::from_secs(20), + connect(&bin, &approot, &audit_dir, "safe", offered.clone(), true), + ) + .await + { + Ok(Ok(session)) => { + let info = session.service.peer_info(); + println!( + "offered {offered}: connected in {} ms, negotiated {:?}, server {:?}", + session.connect_ms, + info.as_ref().map(|i| i.protocol_version.to_string()), + info.as_ref() + .and_then(|i| i.server_info.as_ref()) + .map(|s| format!("{} {}", s.name, s.version)), + ); + let tools = session.service.list_all_tools().await; + println!( + " tools listed: {:?}", + tools.map(|t| t.len()).map_err(|e| e.to_string()) + ); + let _ = session.service.cancel().await; + } + Ok(Err(err)) => println!("offered {offered}: failed: {err}"), + Err(_) => println!("offered {offered}: timed out"), + } + } + + println!("\n== session in safe mode, handshake lifecycle =="); + let session = connect( + &bin, + &approot, + &audit_dir, + "safe", + ProtocolVersion::LATEST_WITH_INITIALIZE, + true, + ) + .await?; + if let Some(info) = session.service.peer_info() { + println!("negotiated revision: {}", info.protocol_version); + println!("server info: {:?}", info.server_info); + println!( + "capabilities: {}", + clip( + &serde_json::to_string(&info.capabilities).unwrap_or_default(), + 400 + ) + ); + println!( + "instructions: {} chars, starting {:?}", + info.instructions.as_deref().map_or(0, str::len), + info.instructions.as_deref().map(|i| clip(i, 160)) + ); + } + + println!("\n== tools =="); + let tools = session.service.list_all_tools().await?; + for tool in &tools { + let annotations = tool.annotations.as_ref().map(|a| { + format!( + "readOnly={:?} destructive={:?} idempotent={:?} openWorld={:?}", + a.read_only_hint, a.destructive_hint, a.idempotent_hint, a.open_world_hint + ) + }); + let schema = serde_json::Value::Object((*tool.input_schema).clone()); + let properties: Vec = schema + .get("properties") + .and_then(|p| p.as_object()) + .map(|p| p.keys().cloned().collect()) + .unwrap_or_default(); + println!( + "{:<24} title={:?} args={:?} required={} {}", + tool.name, + tool.title, + properties, + schema + .get("required") + .map_or_else(|| "[]".to_string(), ToString::to_string), + annotations.unwrap_or_default(), + ); + } + if let Some(tool) = tools.iter().find(|t| t.name == "run_select_query") { + println!( + "run_select_query input schema: {}", + serde_json::Value::Object((*tool.input_schema).clone()) + ); + println!( + "run_select_query description: {:?}", + tool.description.as_deref().map(|d| clip(d, 300)) + ); + println!( + "run_select_query has an output schema: {}", + tool.output_schema.is_some() + ); + } + + println!("\n== read tools =="); + call(&session, "server_info", serde_json::json!({})).await; + call(&session, "list_providers", serde_json::json!({})).await; + call( + &session, + "pull_provider", + serde_json::json!({ "provider": "homebrew" }), + ) + .await; + call( + &session, + "list_services", + serde_json::json!({ "provider": "homebrew" }), + ) + .await; + call( + &session, + "run_select_query", + serde_json::json!({ "sql": "SELECT name, license, versions FROM homebrew.formula.formula WHERE formula_name = 'wget'" }), + ) + .await; + call( + &session, + "run_select_query", + serde_json::json!({ "sql": "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'wget' UNION ALL SELECT name FROM homebrew.formula.formula WHERE formula_name = 'jq'" }), + ) + .await; + + println!("\n== failures on the read path =="); + call( + &session, + "run_select_query", + serde_json::json!({ "sql": "SELEC 1" }), + ) + .await; + call( + &session, + "run_select_query", + serde_json::json!({ "sql": "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'no-such-formula-xyz-123'" }), + ) + .await; + call( + &session, + "list_services", + serde_json::json!({ "provider": "no_such_provider" }), + ) + .await; + call(&session, "run_select_query", serde_json::json!({})).await; + call(&session, "no_such_tool", serde_json::json!({})).await; + // A write sent to the read tool must be refused in every mode. + call( + &session, + "run_select_query", + serde_json::json!({ "sql": "DELETE FROM github.repos.repos WHERE owner = 'nobody-xyz' AND repo = 'nothing-xyz'" }), + ) + .await; + + println!("\n== approval flow in safe mode =="); + let delete = serde_json::json!({ "sql": "DELETE FROM github.repos.repos WHERE owner = 'nobody-xyz' AND repo = 'nothing-xyz'" }); + println!("-- operator declines"); + *session.answer.lock().unwrap() = Answer::Decline; + call(&session, "run_mutation_query", delete.clone()).await; + println!("-- operator cancels"); + *session.answer.lock().unwrap() = Answer::Cancel; + call(&session, "run_mutation_query", delete.clone()).await; + println!( + "-- operator accepts (no credentials are configured, so the provider call cannot succeed)" + ); + *session.answer.lock().unwrap() = Answer::Accept; + call(&session, "run_mutation_query", delete.clone()).await; + println!("-- lifecycle operation, declined"); + *session.answer.lock().unwrap() = Answer::Decline; + call( + &session, + "run_lifecycle_operation", + serde_json::json!({ "sql": "EXEC github.repos.repos.list_for_org @org = 'stackql'" }), + ) + .await; + + let stderr = session.stderr.lock().unwrap().clone(); + println!("\nserver stderr lines: {}", stderr.len()); + for line in stderr.iter().take(6) { + println!(" {}", clip(line, 200)); + } + close(session).await; + + println!("\n== a client that does not advertise elicitation =="); + let session = connect( + &bin, + &approot, + &audit_dir, + "safe", + ProtocolVersion::LATEST_WITH_INITIALIZE, + false, + ) + .await?; + call(&session, "run_mutation_query", delete.clone()).await; + let _ = session.service.cancel().await; + + println!("\n== read_only mode =="); + let session = connect( + &bin, + &approot, + &audit_dir, + "read_only", + ProtocolVersion::LATEST_WITH_INITIALIZE, + true, + ) + .await?; + call(&session, "server_info", serde_json::json!({})).await; + call(&session, "run_mutation_query", delete.clone()).await; + let _ = session.service.cancel().await; + + println!("\n== the newest revision (no handshake), approval by input_required round trip =="); + match connect( + &bin, + &approot, + &audit_dir, + "safe", + ProtocolVersion::LATEST, + true, + ) + .await + { + Ok(session) => { + *session.answer.lock().unwrap() = Answer::Decline; + call(&session, "list_providers", serde_json::json!({})).await; + call(&session, "run_mutation_query", delete).await; + let _ = session.service.cancel().await; + } + Err(err) => println!("could not connect on the newest revision: {err}"), + } + + print_audit(&audit_dir); + Ok(()) +} diff --git a/src-tauri/examples/pgwire_spike.rs b/src-tauri/examples/pgwire_spike.rs new file mode 100644 index 0000000..28fb1a0 --- /dev/null +++ b/src-tauri/examples/pgwire_spike.rs @@ -0,0 +1,1305 @@ +//! pg wire spike against a real `stackql srv`. +//! +//! Starts the engine on a free loopback port with a scratch approot, then +//! probes the wire protocol twice: once with hand-built protocol frames, so +//! nothing is hidden by a client library, and once through `tokio-postgres`, +//! the client the host uses. The output is the evidence recorded in +//! `docs/spike-pgwire.md`. +//! +//! Run from `src-tauri`: +//! +//! ```text +//! cargo run --example pgwire_spike -- [--bin ] [--approot ] [--only
] +//! ``` +//! +//! No cloud credentials are used. Statements go to provider metadata and to +//! two providers that serve public data without authentication. + +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::process::Stdio; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use futures_util::{StreamExt, future}; +use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader}; +use tokio::net::{TcpListener, TcpStream}; +use tokio::process::{Child, Command}; +use tokio_postgres::{AsyncMessage, Config, NoTls, SimpleQueryMessage}; + +type AnyError = Box; +type Log = Arc>>; + +const FORMULAS: &[&str] = &[ + "wget", + "curl", + "git", + "jq", + "go", + "node", + "rust", + "cmake", + "make", + "sqlite", + "zlib", + "xz", + "zstd", + "readline", + "ncurses", + "gettext", + "pcre2", + "libyaml", + "tree", + "htop", + "tmux", + "vim", + "nginx", + "redis", + "lua", + "ruby", + "perl", + "php", + "gcc", + "llvm", + "bash", + "zsh", + "fish", + "less", + "nano", + "rsync", + "gnupg", + "pandoc", + "ffmpeg", + "imagemagick", + "graphviz", + "protobuf", + "grpc", + "boost", + "openjdk", + "maven", + "gradle", + "kotlin", + "scala", + "sbt", + "leiningen", + "clojure", + "erlang", + "elixir", + "ghc", + "ocaml", + "opam", + "nim", + "zig", + "deno", +]; + +struct Server { + child: Child, + port: u16, + log: Log, + started: Instant, +} + +impl Server { + async fn start(bin: &PathBuf, approot: &PathBuf, extra: &[&str]) -> Result { + // Bind to port 0 to have the OS pick a free port, then release it. + let port = TcpListener::bind("127.0.0.1:0").await?.local_addr()?.port(); + let mut cmd = Command::new(bin); + cmd.arg("srv") + .args(["--pgsrv.address", "127.0.0.1"]) + .args(["--pgsrv.port", &port.to_string()]) + .arg("--approot") + .arg(approot) + .args(extra) + .current_dir(approot) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .kill_on_drop(true); + let started = Instant::now(); + let mut child = cmd.spawn()?; + let log: Log = Arc::default(); + if let Some(out) = child.stdout.take() { + tokio::spawn(pump(out, "stdout", log.clone(), started)); + } + if let Some(err) = child.stderr.take() { + tokio::spawn(pump(err, "stderr", log.clone(), started)); + } + Ok(Self { + child, + port, + log, + started, + }) + } + + /// Returns the log lines captured since `mark` and the new mark. + fn log_since(&self, mark: usize) -> (Vec, usize) { + let log = self.log.lock().unwrap(); + let lines = log[mark..] + .iter() + .map(|(at, stream, line)| format!("[{:>7.3}s {stream}] {line}", at.as_secs_f64())) + .collect(); + (lines, log.len()) + } + + fn mark(&self) -> usize { + self.log.lock().unwrap().len() + } +} + +async fn pump( + reader: R, + stream: &'static str, + log: Log, + started: Instant, +) { + let mut lines = BufReader::new(reader).lines(); + while let Ok(Some(line)) = lines.next_line().await { + log.lock().unwrap().push((started.elapsed(), stream, line)); + } +} + +// --- raw protocol ----------------------------------------------------------- + +#[derive(Debug, Clone)] +struct Field { + name: String, + table_oid: u32, + attnum: i16, + type_oid: u32, + typlen: i16, + typmod: i32, + format: i16, +} + +#[derive(Debug, Default)] +struct RawResult { + fields: Vec, + row_descriptions: usize, + rows: Vec>>, + tags: Vec, + errors: Vec>, + notices: Vec>, + other: Vec, + ready: Option, + elapsed: Duration, + first_row_at: Option, +} + +struct Raw { + stream: TcpStream, + pid: Option, + secret: Option, +} + +struct Msg { + kind: u8, + body: Vec, +} + +fn cstr(body: &[u8], pos: &mut usize) -> String { + let start = *pos; + while *pos < body.len() && body[*pos] != 0 { + *pos += 1; + } + let s = String::from_utf8_lossy(&body[start..*pos]).into_owned(); + *pos += 1; + s +} + +fn i16_at(body: &[u8], pos: &mut usize) -> i16 { + let v = i16::from_be_bytes([body[*pos], body[*pos + 1]]); + *pos += 2; + v +} + +fn i32_at(body: &[u8], pos: &mut usize) -> i32 { + let v = i32::from_be_bytes([body[*pos], body[*pos + 1], body[*pos + 2], body[*pos + 3]]); + *pos += 4; + v +} + +fn fields_of(body: &[u8]) -> BTreeMap { + let mut out = BTreeMap::new(); + let mut pos = 0; + while pos < body.len() && body[pos] != 0 { + let code = body[pos] as char; + pos += 1; + out.insert(code, cstr(body, &mut pos)); + } + out +} + +impl Raw { + async fn read_msg(&mut self) -> Result { + let kind = self.stream.read_u8().await?; + let len = self.stream.read_i32().await?; + let mut body = vec![0u8; usize::try_from(len - 4)?]; + self.stream.read_exact(&mut body).await?; + Ok(Msg { kind, body }) + } + + /// Opens a socket and runs the startup handshake. Returns the connection + /// and a description of every message the server sent before it was ready. + async fn connect(port: u16, params: &[(&str, &str)]) -> Result<(Self, Vec), AnyError> { + let stream = TcpStream::connect(("127.0.0.1", port)).await?; + let mut raw = Self { + stream, + pid: None, + secret: None, + }; + let mut body = Vec::new(); + body.extend_from_slice(&196_608i32.to_be_bytes()); // protocol 3.0 + for (k, v) in params { + body.extend_from_slice(k.as_bytes()); + body.push(0); + body.extend_from_slice(v.as_bytes()); + body.push(0); + } + body.push(0); + let mut frame = Vec::new(); + frame.extend_from_slice(&i32::try_from(body.len() + 4)?.to_be_bytes()); + frame.extend_from_slice(&body); + raw.stream.write_all(&frame).await?; + + let mut seen = Vec::new(); + loop { + let msg = raw.read_msg().await?; + let mut pos = 0; + match msg.kind { + b'R' => { + let code = i32_at(&msg.body, &mut pos); + seen.push(format!("Authentication code={code} (0 = AuthenticationOk)")); + } + b'S' => { + let k = cstr(&msg.body, &mut pos); + let v = cstr(&msg.body, &mut pos); + seen.push(format!("ParameterStatus {k}={v}")); + } + b'K' => { + let pid = i32_at(&msg.body, &mut pos); + let secret = i32_at(&msg.body, &mut pos); + raw.pid = Some(pid); + raw.secret = Some(secret); + seen.push(format!("BackendKeyData pid={pid} secret={secret}")); + } + b'N' => seen.push(format!("NoticeResponse {:?}", fields_of(&msg.body))), + b'E' => { + seen.push(format!("ErrorResponse {:?}", fields_of(&msg.body))); + break; + } + b'Z' => { + seen.push(format!("ReadyForQuery status={}", msg.body[0] as char)); + break; + } + other => seen.push(format!( + "message '{}' ({} bytes)", + other as char, + msg.body.len() + )), + } + } + Ok((raw, seen)) + } + + async fn send(&mut self, kind: u8, body: &[u8]) -> Result<(), AnyError> { + let mut frame = vec![kind]; + frame.extend_from_slice(&i32::try_from(body.len() + 4)?.to_be_bytes()); + frame.extend_from_slice(body); + self.stream.write_all(&frame).await?; + Ok(()) + } + + /// Reads backend messages until ReadyForQuery. + async fn collect(&mut self, started: Instant) -> Result { + let mut res = RawResult::default(); + loop { + let msg = self.read_msg().await?; + let mut pos = 0; + match msg.kind { + b'T' => { + res.row_descriptions += 1; + let n = i16_at(&msg.body, &mut pos); + res.fields.clear(); + for _ in 0..n { + let name = cstr(&msg.body, &mut pos); + let table_oid = i32_at(&msg.body, &mut pos).cast_unsigned(); + let attnum = i16_at(&msg.body, &mut pos); + let type_oid = i32_at(&msg.body, &mut pos).cast_unsigned(); + let typlen = i16_at(&msg.body, &mut pos); + let typmod = i32_at(&msg.body, &mut pos); + let format = i16_at(&msg.body, &mut pos); + res.fields.push(Field { + name, + table_oid, + attnum, + type_oid, + typlen, + typmod, + format, + }); + } + } + b'D' => { + res.first_row_at.get_or_insert(started.elapsed()); + let n = i16_at(&msg.body, &mut pos); + let mut row = Vec::new(); + for _ in 0..n { + let len = i32_at(&msg.body, &mut pos); + if len < 0 { + row.push(None); + } else { + let len = usize::try_from(len)?; + let bytes = &msg.body[pos..pos + len]; + pos += len; + row.push(Some(String::from_utf8_lossy(bytes).into_owned())); + } + } + res.rows.push(row); + } + b'C' => res.tags.push(cstr(&msg.body, &mut pos)), + b'E' => res.errors.push(fields_of(&msg.body)), + b'N' => res.notices.push(fields_of(&msg.body)), + b'I' => res.other.push("EmptyQueryResponse".into()), + b'1' => res.other.push("ParseComplete".into()), + b'2' => res.other.push("BindComplete".into()), + b'3' => res.other.push("CloseComplete".into()), + b'n' => res.other.push("NoData".into()), + b't' => { + let n = i16_at(&msg.body, &mut pos); + let oids: Vec = (0..n).map(|_| i32_at(&msg.body, &mut pos)).collect(); + res.other.push(format!("ParameterDescription {oids:?}")); + } + b's' => res.other.push("PortalSuspended".into()), + b'Z' => { + res.ready = Some(msg.body[0] as char); + break; + } + other => res.other.push(format!("message '{}'", other as char)), + } + } + res.elapsed = started.elapsed(); + Ok(res) + } + + async fn simple(&mut self, sql: &str) -> Result { + let started = Instant::now(); + let mut body = sql.as_bytes().to_vec(); + body.push(0); + self.send(b'Q', &body).await?; + self.collect(started).await + } +} + +fn clip(s: &str, max: usize) -> String { + let flat = s.replace(['\r', '\n'], " "); + if flat.chars().count() > max { + let head: String = flat.chars().take(max).collect(); + format!("{head}... [{} chars]", flat.chars().count()) + } else { + flat + } +} + +fn print_result(sql: &str, res: &RawResult, sample_rows: usize) { + println!("\n> {}", clip(sql, 200)); + println!( + " elapsed {:.0} ms, first row at {}, RowDescription messages {}, rows {}, tags {:?}, ready {:?}", + res.elapsed.as_secs_f64() * 1000.0, + res.first_row_at.map_or("-".to_string(), |d| format!( + "{:.0} ms", + d.as_secs_f64() * 1000.0 + )), + res.row_descriptions, + res.rows.len(), + res.tags, + res.ready + ); + for f in &res.fields { + println!( + " column {:<16} type_oid={:<5} typlen={:<3} typmod={:<3} format={} table_oid={} attnum={}", + f.name, f.type_oid, f.typlen, f.typmod, f.format, f.table_oid, f.attnum + ); + } + for row in res.rows.iter().take(sample_rows) { + let cells: Vec = row + .iter() + .map(|c| c.as_ref().map_or("NULL".to_string(), |v| clip(v, 60))) + .collect(); + println!(" row {cells:?}"); + } + for e in &res.errors { + let shown: BTreeMap = e.iter().map(|(k, v)| (*k, clip(v, 240))).collect(); + println!(" ERROR {shown:?}"); + } + for n in &res.notices { + let shown: BTreeMap = n.iter().map(|(k, v)| (*k, clip(v, 240))).collect(); + println!(" NOTICE {shown:?}"); + } + if !res.other.is_empty() { + println!(" other {:?}", res.other); + } +} + +fn print_server_log(server: &Server, mark: usize) -> usize { + let (lines, next) = server.log_since(mark); + for line in lines.iter().take(12) { + println!(" srv {}", clip(line, 260)); + } + if lines.len() > 12 { + println!(" srv ... {} more lines", lines.len() - 12); + } + next +} + +async fn pg(port: u16) -> Result<(tokio_postgres::Client, Arc>>), AnyError> { + let mut cfg = Config::new(); + cfg.host("127.0.0.1") + .port(port) + .user("stackql") + .dbname("stackql") + .application_name("stackql-workbench-spike") + .connect_timeout(Duration::from_secs(5)); + let (client, mut connection) = cfg.connect(NoTls).await?; + let notices: Arc>> = Arc::default(); + let sink = notices.clone(); + tokio::spawn(async move { + // Drive the connection through poll_message so notices are visible. + let mut messages = futures_util::stream::poll_fn(move |cx| connection.poll_message(cx)); + while let Some(msg) = messages.next().await { + match msg { + Ok(AsyncMessage::Notice(n)) => sink.lock().unwrap().push(format!( + "severity={} code={} message={}", + n.severity(), + n.code().code(), + n.message() + )), + Ok(_) => {} + Err(e) => { + sink.lock().unwrap().push(format!("connection error: {e}")); + break; + } + } + } + }); + Ok((client, notices)) +} + +fn describe_pg_error(e: &tokio_postgres::Error) -> String { + match e.as_db_error() { + Some(db) => format!( + "DbError severity={} code={} message={:?} detail={:?} hint={:?} position={:?} where={:?} routine={:?}", + db.severity(), + db.code().code(), + clip(db.message(), 200), + db.detail().map(|d| clip(d, 120)), + db.hint(), + db.position(), + db.where_(), + db.routine() + ), + None => format!("non-db error: {e} (closed={})", e.is_closed()), + } +} + +fn union_of(names: &[&str]) -> String { + names + .iter() + .map(|n| format!("SELECT name FROM homebrew.formula.formula WHERE formula_name = '{n}'")) + .collect::>() + .join(" UNION ALL ") +} + +// --- sections --------------------------------------------------------------- + +async fn section_readiness(bin: &PathBuf, approot: &PathBuf) -> Result<(), AnyError> { + println!("\n== readiness =="); + for run in 1..=5 { + let mut server = Server::start(bin, approot, &[]).await?; + let mut tcp_at = None; + let mut ready_at = None; + let mut query_at = None; + let mut attempts = 0u32; + let deadline = Instant::now() + Duration::from_secs(30); + while Instant::now() < deadline { + attempts += 1; + // Bound each attempt: on Windows a refused loopback connect is retried + // by the OS for about half a second, which would hide the real figure. + let attempt = tokio::time::timeout( + Duration::from_millis(40), + TcpStream::connect(("127.0.0.1", server.port)), + ) + .await; + if matches!(attempt, Ok(Ok(_))) { + tcp_at.get_or_insert(server.started.elapsed()); + if let Ok((mut raw, _)) = Raw::connect(server.port, &[("user", "stackql")]).await { + ready_at.get_or_insert(server.started.elapsed()); + if let Ok(res) = raw.simple("SHOW VERSION").await + && res.errors.is_empty() + && !res.rows.is_empty() + { + query_at = Some(server.started.elapsed()); + break; + } + } + } + tokio::time::sleep(Duration::from_millis(10)).await; + } + let ms = |d: Option| { + d.map_or("never".to_string(), |d| { + format!("{:.0} ms", d.as_secs_f64() * 1000.0) + }) + }; + println!( + "run {run}: tcp accept {}, handshake ready {}, first SHOW VERSION result {}, attempts {attempts}", + ms(tcp_at), + ms(ready_at), + ms(query_at) + ); + if run == 1 { + print_server_log(&server, 0); + } + server.child.kill().await?; + } + Ok(()) +} + +async fn section_handshake(server: &Server) -> Result<(), AnyError> { + println!("\n== startup, auth and TLS negotiation =="); + + // SSLRequest: length 8, code 80877103. The reply is one byte. + let mut s = TcpStream::connect(("127.0.0.1", server.port)).await?; + let mut frame = Vec::new(); + frame.extend_from_slice(&8i32.to_be_bytes()); + frame.extend_from_slice(&80_877_103i32.to_be_bytes()); + s.write_all(&frame).await?; + let mut reply = [0u8; 1]; + match tokio::time::timeout(Duration::from_secs(3), s.read_exact(&mut reply)).await { + Ok(Ok(_)) => println!( + "SSLRequest reply: '{}' (S = TLS, N = no TLS)", + reply[0] as char + ), + Ok(Err(e)) => println!("SSLRequest reply: read error {e}"), + Err(_) => println!("SSLRequest reply: none within 3 s"), + } + + for params in [ + vec![("user", "stackql"), ("database", "stackql")], + vec![("user", "anyone")], + vec![ + ("user", "stackql"), + ("database", "nonexistent_db"), + ("application_name", "spike"), + ("client_encoding", "UTF8"), + ], + vec![], + ] { + match Raw::connect(server.port, ¶ms).await { + Ok((_, seen)) => { + println!("startup params {params:?}:"); + for line in seen { + println!(" {line}"); + } + } + Err(e) => println!("startup params {params:?}: failed: {e}"), + } + } + + // A password is not requested, so check that one is not required either. + let mut cfg = Config::new(); + cfg.host("127.0.0.1").port(server.port).user("stackql"); + match cfg.connect(NoTls).await { + Ok((client, connection)) => { + println!( + "tokio-postgres connect (user only, NoTls): ok, server_version={:?}, client_encoding={:?}", + connection.parameter("server_version"), + connection.parameter("client_encoding") + ); + tokio::spawn(connection); + println!(" is_closed={}", client.is_closed()); + } + Err(e) => println!("tokio-postgres connect failed: {}", describe_pg_error(&e)), + } + Ok(()) +} + +async fn section_metadata(server: &Server) -> Result<(), AnyError> { + println!("\n== metadata statements: column names, types and shapes =="); + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let statements = [ + "SHOW VERSION", + "SHOW EXTENDED VERSION", + "SHOW PROVIDERS", + "SHOW EXTENDED PROVIDERS", + "REGISTRY LIST", + "REGISTRY PULL homebrew", + "REGISTRY PULL github", + "SHOW PROVIDERS", + "SHOW SERVICES IN homebrew", + "SHOW EXTENDED SERVICES IN homebrew", + "SHOW SERVICES IN github LIKE '%repo%'", + "SHOW RESOURCES IN homebrew.formula", + "SHOW EXTENDED RESOURCES IN homebrew.formula", + "SHOW METHODS IN homebrew.formula.formula", + "SHOW EXTENDED METHODS IN homebrew.formula.formula", + "SHOW EXTENDED METHODS IN github.repos.repos", + "DESCRIBE homebrew.formula.formula", + "DESCRIBE EXTENDED homebrew.formula.formula", + "DESCRIBE METHOD homebrew.formula.formula.get_formula", + "DESCRIBE EXTENDED METHOD homebrew.formula.formula.get_formula", + "DESCRIBE METHOD EXTENDED homebrew.formula.formula.get_formula", + "DESCRIBE homebrew.formula.vw_versions", + ]; + for sql in statements { + let mark = server.mark(); + let res = raw.simple(sql).await?; + print_result(sql, &res, 3); + print_server_log(server, mark); + } + Ok(()) +} + +async fn section_values(server: &Server) -> Result<(), AnyError> { + println!("\n== value types: are values text? =="); + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + for sql in [ + "SELECT 1 AS one, 'x' AS s, 1.5 AS f, NULL AS n, 1 = 1 AS b", + "SELECT name, deprecated, versions, aliases, revision, tap FROM homebrew.formula.formula WHERE formula_name = 'wget'", + "SELECT name, id, private, stargazers_count, created_at, owner, topics, license FROM github.repos.repos WHERE org = 'stackql' LIMIT 2", + "SELECT count(*) AS n FROM github.repos.repos WHERE org = 'stackql'", + "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'wget' AND 1 = 0", + ] { + let res = raw.simple(sql).await?; + print_result(sql, &res, 2); + } + Ok(()) +} + +async fn section_protocols(server: &Server) -> Result<(), AnyError> { + println!("\n== query protocols =="); + let (client, notices) = pg(server.port).await?; + + println!("-- simple protocol through tokio-postgres"); + match client.simple_query("SHOW PROVIDERS").await { + Ok(msgs) => { + for m in &msgs { + match m { + SimpleQueryMessage::RowDescription(cols) => println!( + " RowDescription {:?}", + cols.iter() + .map(|c| c.name().to_string()) + .collect::>() + ), + SimpleQueryMessage::Row(r) => println!( + " Row {:?}", + (0..r.len()).map(|i| r.get(i)).collect::>() + ), + SimpleQueryMessage::CommandComplete(n) => println!(" CommandComplete {n}"), + _ => println!(" other message"), + } + } + } + Err(e) => println!(" simple_query failed: {}", describe_pg_error(&e)), + } + + println!("-- simple protocol, several statements in one message"); + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + for sql in [ + "SHOW VERSION; SHOW PROVIDERS;", + "SHOW VERSION; SELEC 1; SHOW PROVIDERS;", + "", + ";", + "-- only a comment", + "SHOW VERSION -- trailing comment", + "SHOW VERSION;", + ] { + let res = raw.simple(sql).await?; + print_result(sql, &res, 1); + } + + println!("-- simple_query_raw: do rows arrive incrementally?"); + let started = Instant::now(); + match client.simple_query_raw(&union_of(&FORMULAS[..12])).await { + Ok(stream) => { + let mut stream = std::pin::pin!(stream); + while let Some(item) = stream.next().await { + let at = started.elapsed().as_millis(); + match item { + Ok(SimpleQueryMessage::RowDescription(_)) => { + println!(" {at:>5} ms RowDescription") + } + Ok(SimpleQueryMessage::Row(r)) => println!(" {at:>5} ms Row {:?}", r.get(0)), + Ok(SimpleQueryMessage::CommandComplete(n)) => { + println!(" {at:>5} ms CommandComplete {n}"); + } + Ok(_) => println!(" {at:>5} ms other"), + Err(e) => println!(" {at:>5} ms error {}", describe_pg_error(&e)), + } + } + } + Err(e) => println!(" simple_query_raw failed: {}", describe_pg_error(&e)), + } + + println!("-- extended protocol: prepare (Parse, Describe, Sync)"); + for sql in [ + "SHOW PROVIDERS", + "SELECT name, versions FROM homebrew.formula.formula WHERE formula_name = 'wget'", + "SELECT name FROM homebrew.formula.formula WHERE formula_name = $1", + ] { + match tokio::time::timeout(Duration::from_secs(20), client.prepare(sql)).await { + Ok(Ok(stmt)) => println!( + " prepare ok: {} -> params {:?}, columns {:?}", + clip(sql, 80), + stmt.params(), + stmt.columns() + .iter() + .map(|c| format!("{}:{}", c.name(), c.type_())) + .collect::>() + ), + Ok(Err(e)) => println!( + " prepare failed: {} -> {}", + clip(sql, 80), + describe_pg_error(&e) + ), + Err(_) => println!(" prepare timed out: {}", clip(sql, 80)), + } + } + + println!("-- extended protocol: query without parameters"); + match tokio::time::timeout(Duration::from_secs(20), client.query("SHOW PROVIDERS", &[])).await { + Ok(Ok(rows)) => { + println!(" query ok: {} rows", rows.len()); + for row in rows.iter().take(2) { + let cols: Vec = row + .columns() + .iter() + .enumerate() + .map(|(i, c)| { + let v: Result, _> = row.try_get(i); + format!("{}:{}={v:?}", c.name(), c.type_()) + }) + .collect(); + println!(" row {cols:?}"); + } + } + Ok(Err(e)) => println!(" query failed: {}", describe_pg_error(&e)), + Err(_) => println!(" query timed out"), + } + + println!("-- extended protocol: query with a text parameter"); + let sql = "SELECT name, full_name FROM homebrew.formula.formula WHERE formula_name = $1"; + match tokio::time::timeout(Duration::from_secs(20), client.query(sql, &[&"jq"])).await { + Ok(Ok(rows)) => { + println!(" query ok: {} rows", rows.len()); + for row in &rows { + let v: Result, _> = row.try_get(0); + println!(" row name={v:?}"); + } + } + Ok(Err(e)) => println!(" query failed: {}", describe_pg_error(&e)), + Err(_) => println!(" query timed out"), + } + + println!("-- extended protocol: query_typed (no separate prepare round trip)"); + let typed = client + .query_typed(sql, &[(&"wget", tokio_postgres::types::Type::TEXT)]) + .await; + match typed { + Ok(rows) => println!(" query_typed ok: {} rows", rows.len()), + Err(e) => println!(" query_typed failed: {}", describe_pg_error(&e)), + } + + println!("-- raw extended protocol frames for one statement"); + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let started = Instant::now(); + let mut parse = Vec::new(); + parse.push(0); // unnamed statement + parse.extend_from_slice(b"SHOW PROVIDERS\0"); + parse.extend_from_slice(&0i16.to_be_bytes()); + raw.send(b'P', &parse).await?; + raw.send(b'D', b"S\0").await?; // describe statement + let mut bind = vec![0, 0]; // unnamed portal, unnamed statement + bind.extend_from_slice(&0i16.to_be_bytes()); // parameter format codes + bind.extend_from_slice(&0i16.to_be_bytes()); // parameters + bind.extend_from_slice(&0i16.to_be_bytes()); // result format codes + raw.send(b'B', &bind).await?; + raw.send(b'D', b"P\0").await?; // describe portal + let mut exec = vec![0]; + exec.extend_from_slice(&0i32.to_be_bytes()); + raw.send(b'E', &exec).await?; + raw.send(b'S', &[]).await?; + match tokio::time::timeout(Duration::from_secs(10), raw.collect(started)).await { + Ok(Ok(res)) => print_result( + "Parse/Describe/Bind/Describe/Execute/Sync SHOW PROVIDERS", + &res, + 2, + ), + Ok(Err(e)) => println!(" raw extended failed: {e}"), + Err(_) => println!(" raw extended timed out"), + } + + println!( + "notices seen on the tokio-postgres connection: {:?}", + notices.lock().unwrap() + ); + Ok(()) +} + +async fn section_errors(server: &Server) -> Result<(), AnyError> { + println!("\n== errors: fields and codes =="); + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let statements = [ + "SELEC 1", + "SHOW SERVICES IN nosuchprovider", + "SHOW RESOURCES IN homebrew.nosuchservice", + "SELECT * FROM homebrew.nosuch.thing WHERE x = 1", + "SELECT name FROM homebrew.formula.formula", + "SELECT nosuchcolumn FROM homebrew.formula.formula WHERE formula_name = 'wget'", + "DESCRIBE homebrew.formula.nosuchresource", + "REGISTRY PULL nosuchprovider", + ]; + for sql in statements { + let mark = server.mark(); + let res = raw.simple(sql).await?; + print_result(sql, &res, 1); + print_server_log(server, mark); + } + let res = raw.simple("SHOW VERSION").await?; + println!( + "\nconnection still usable after the errors: {}", + res.errors.is_empty() && res.rows.len() == 1 + ); + + println!("-- the same errors through tokio-postgres"); + let (client, notices) = pg(server.port).await?; + for sql in ["SELEC 1", "SHOW SERVICES IN nosuchprovider"] { + match client.simple_query(sql).await { + Ok(m) => println!(" {sql}: ok with {} messages", m.len()), + Err(e) => println!(" {sql}: {}", describe_pg_error(&e)), + } + } + println!(" client.is_closed after errors: {}", client.is_closed()); + println!(" notices: {:?}", notices.lock().unwrap()); + Ok(()) +} + +async fn section_upstream(bin: &PathBuf, approot: &PathBuf) -> Result<(), AnyError> { + println!("\n== upstream provider failures =="); + for (label, extra) in [ + ("default flags", vec![]), + ("--pgsrv.debug.enable", vec!["--pgsrv.debug.enable"]), + ("--pgsrv.loglevel DEBUG", vec!["--pgsrv.loglevel", "DEBUG"]), + ("--http.log.enabled", vec!["--http.log.enabled"]), + ] { + println!("\n-- server started with {label}"); + let mut server = Server::start(bin, approot, &extra).await?; + wait_ready(&server).await?; + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let (client, notices) = pg(server.port).await?; + for sql in [ + // 404 from the upstream API. + "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'no-such-formula-xyz-123'", + // One good branch and one failing branch. + "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'wget' UNION ALL SELECT name FROM homebrew.formula.formula WHERE formula_name = 'no-such-formula-xyz-123'", + // A provider that needs credentials for this resource, none configured. + "SELECT login FROM github.users.users", + "SELECT id FROM github.repos.repos WHERE org = 'no-such-org-xyz-9871236'", + ] { + let mark = server.mark(); + let res = raw.simple(sql).await?; + print_result(sql, &res, 2); + print_server_log(&server, mark); + match client.simple_query(sql).await { + Ok(m) => println!(" tokio-postgres: ok with {} messages", m.len()), + Err(e) => println!(" tokio-postgres: {}", describe_pg_error(&e)), + } + } + println!( + " notices via tokio-postgres poll_message: {:?}", + notices.lock().unwrap() + ); + server.child.kill().await?; + } + Ok(()) +} + +async fn section_concurrency(server: &Server) -> Result<(), AnyError> { + println!("\n== concurrent connections =="); + let mut conns = Vec::new(); + for _ in 0..4 { + let (raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + conns.push(raw); + } + println!( + "backend key data per connection: {:?}", + conns.iter().map(|c| (c.pid, c.secret)).collect::>() + ); + + // The same slow statement alone, then on four connections at once. + let slow = union_of(&FORMULAS[..8]); + let alone = conns[0].simple(&slow).await?; + println!( + "one connection, 8 upstream calls: {:.0} ms, rows {}", + alone.elapsed.as_secs_f64() * 1000.0, + alone.rows.len() + ); + + let started = Instant::now(); + let results = future::join_all(conns.iter_mut().enumerate().map(|(i, c)| { + let sql = union_of(&FORMULAS[i * 8..i * 8 + 8]); + async move { (i, c.simple(&sql).await) } + })) + .await; + println!( + "four connections at once, wall time {:.0} ms", + started.elapsed().as_secs_f64() * 1000.0 + ); + for (i, res) in results { + let res = res?; + let names: Vec = res.rows.iter().filter_map(|r| r[0].clone()).collect(); + println!( + " conn {i}: {:.0} ms, rows {}, correct rows {}, errors {}", + res.elapsed.as_secs_f64() * 1000.0, + res.rows.len(), + names == FORMULAS[i * 8..i * 8 + 8], + res.errors.len() + ); + } + + // A fast metadata statement while another connection is busy. + let (mut a, mut b) = { + let mut it = conns.into_iter(); + (it.next().unwrap(), it.next().unwrap()) + }; + let started = Instant::now(); + let slow = union_of(&FORMULAS[20..40]); + let (slow_res, fast_res) = tokio::join!(a.simple(&slow), async { + tokio::time::sleep(Duration::from_millis(300)).await; + let res = b.simple("SHOW PROVIDERS").await; + (res, started.elapsed()) + }); + let slow_res = slow_res?; + let (fast_res, fast_done) = fast_res; + let fast_res = fast_res?; + println!( + "metadata statement issued 300 ms into a {:.0} ms statement on another connection: finished at {:.0} ms (took {:.0} ms)", + slow_res.elapsed.as_secs_f64() * 1000.0, + fast_done.as_secs_f64() * 1000.0, + fast_res.elapsed.as_secs_f64() * 1000.0 + ); + + println!("-- session independence"); + // An error on one connection must not affect another. + let bad = a.simple("SELEC 1").await?; + let good = b.simple("SHOW VERSION").await?; + println!( + "error on A (errors {}), then B still fine: {}", + bad.errors.len(), + good.errors.is_empty() && good.rows.len() == 1 + ); + // Session-scoped settings, if the engine accepts them. + for sql in [ + "SET SESSION \"$.auth.github.type\" = 'null_auth'", + "SHOW TRANSACTION ISOLATION LEVEL", + "BEGIN", + "COMMIT", + "CREATE TABLE spike_t (id int)", + "SELECT * FROM spike_t", + ] { + let res = a.simple(sql).await?; + print_result(&format!("[A] {sql}"), &res, 2); + } + let res = b.simple("SELECT * FROM spike_t").await?; + print_result("[B] SELECT * FROM spike_t", &res, 2); + // Closing one connection must not affect the other. + drop(a); + tokio::time::sleep(Duration::from_millis(200)).await; + let res = b.simple("SHOW VERSION").await?; + println!( + "B after A closed: rows {}, errors {}", + res.rows.len(), + res.errors.len() + ); + Ok(()) +} + +/// Counts upstream HTTP requests the engine logged, split at `cut`. +fn http_calls(server: &Server, mark: usize, cut: Duration) -> (usize, usize) { + let log = server.log.lock().unwrap(); + let mut before = 0; + let mut after = 0; + for (at, _, line) in &log[mark..] { + if line.contains("http request url") + || line.contains("http request") && line.contains("GET") + { + if *at <= cut { + before += 1; + } else { + after += 1; + } + } + } + (before, after) +} + +async fn section_cancel(bin: &PathBuf, approot: &PathBuf) -> Result<(), AnyError> { + println!("\n== cancel =="); + // --http.log.enabled makes the engine log each upstream request, which shows + // whether work continues after a cancel or a dropped connection. + let mut server = Server::start(bin, approot, &["--http.log.enabled"]).await?; + wait_ready(&server).await?; + let slow = union_of(FORMULAS); + let cancel_after = Duration::from_millis(250); + + println!( + "-- baseline: {} upstream calls, not cancelled", + FORMULAS.len() + ); + let (mut raw, seen) = Raw::connect(server.port, &[("user", "stackql")]).await?; + println!( + " BackendKeyData in handshake: {}", + seen.iter().any(|l| l.starts_with("BackendKeyData")) + ); + let mark = server.mark(); + let base = raw.simple(&slow).await?; + let (lines, _) = server.log_since(mark); + println!( + " elapsed {:.0} ms, first row at {:?} ms, rows {}, errors {}, engine log lines {}", + base.elapsed.as_secs_f64() * 1000.0, + base.first_row_at.map(|d| d.as_millis()), + base.rows.len(), + base.errors.len(), + lines.len() + ); + for line in lines.iter().take(3) { + println!(" srv {}", clip(line, 200)); + } + + println!( + "-- tokio-postgres cancel_token().cancel_query sent {} ms in", + cancel_after.as_millis() + ); + let (client, _) = pg(server.port).await?; + let token = client.cancel_token(); + let mark = server.mark(); + let cut = server.started.elapsed() + cancel_after; + let canceller = tokio::spawn(async move { + tokio::time::sleep(cancel_after).await; + token.cancel_query(NoTls).await.map_err(|e| e.to_string()) + }); + let started = Instant::now(); + let outcome = client.simple_query(&slow).await; + let elapsed = started.elapsed(); + println!(" cancel_query result: {:?}", canceller.await?); + match outcome { + Ok(msgs) => println!( + " statement completed normally in {:.0} ms with {} messages", + elapsed.as_secs_f64() * 1000.0, + msgs.len() + ), + Err(e) => println!( + " statement failed after {:.0} ms: {}", + elapsed.as_secs_f64() * 1000.0, + describe_pg_error(&e) + ), + } + let (before, after) = http_calls(&server, mark, cut); + println!(" upstream requests logged before the cancel: {before}, after: {after}"); + + println!( + "-- closing the client socket {} ms into the statement", + cancel_after.as_millis() + ); + let (mut raw, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let mut body = slow.as_bytes().to_vec(); + body.push(0); + let mark = server.mark(); + let cut = server.started.elapsed() + cancel_after; + raw.send(b'Q', &body).await?; + tokio::time::sleep(cancel_after).await; + drop(raw); + // Give the engine time to finish, or not, whatever it was doing. + tokio::time::sleep(base.elapsed + Duration::from_secs(2)).await; + let (before, after) = http_calls(&server, mark, cut); + println!(" upstream requests logged before the close: {before}, after: {after}"); + let (mut probe, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let res = probe.simple("SHOW VERSION").await?; + println!( + " engine still serving new connections: {}", + res.rows.len() == 1 + ); + + println!( + "-- dropping the tokio-postgres client {} ms into the statement", + cancel_after.as_millis() + ); + let (client, _) = pg(server.port).await?; + let mark = server.mark(); + let cut = server.started.elapsed() + cancel_after; + let slow_owned = slow.clone(); + let task = tokio::spawn(async move { client.simple_query(&slow_owned).await.map(|m| m.len()) }); + tokio::time::sleep(cancel_after).await; + task.abort(); + tokio::time::sleep(base.elapsed + Duration::from_secs(2)).await; + let (before, after) = http_calls(&server, mark, cut); + println!(" upstream requests logged before the drop: {before}, after: {after}"); + + server.child.kill().await?; + Ok(()) +} + +async fn section_notices(bin: &PathBuf, approot: &PathBuf) -> Result<(), AnyError> { + println!("\n== notices under --pgsrv.debug.enable =="); + let mut server = Server::start(bin, approot, &["--pgsrv.debug.enable"]).await?; + wait_ready(&server).await?; + let bad1 = + "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'no-such-formula-aaa'"; + let bad2 = "SELECT id FROM github.repos.repos WHERE org = 'no-such-org-xyz-9871236'"; + let good = "SELECT name FROM homebrew.formula.formula WHERE formula_name = 'wget'"; + let summarise = |label: &str, res: &RawResult| { + let details: Vec = res + .notices + .iter() + .map(|n| { + let d = n.get(&'D').cloned().unwrap_or_default(); + format!( + "detail {} chars, 'status code' occurrences {}, starts {:?}", + d.chars().count(), + d.matches("http response status code").count(), + clip(&d, 48) + ) + }) + .collect(); + println!( + " {label}: rows {}, tags {:?}, errors {}, notices {} {:?}", + res.rows.len(), + res.tags, + res.errors.len(), + res.notices.len(), + details + ); + }; + let (mut a, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + let (mut b, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + summarise("A SHOW PROVIDERS", &a.simple("SHOW PROVIDERS").await?); + summarise("A good select", &a.simple(good).await?); + summarise("A failing select 1", &a.simple(bad1).await?); + summarise("A SHOW PROVIDERS", &a.simple("SHOW PROVIDERS").await?); + summarise("A good select", &a.simple(good).await?); + summarise("A failing select 2", &a.simple(bad2).await?); + summarise("A syntax error", &a.simple("SELEC 1").await?); + summarise("A REGISTRY LIST", &a.simple("REGISTRY LIST").await?); + summarise( + "B failing select 2 (fresh connection)", + &b.simple(bad2).await?, + ); + summarise("B SHOW PROVIDERS", &b.simple("SHOW PROVIDERS").await?); + let (mut c, _) = Raw::connect(server.port, &[("user", "stackql")]).await?; + summarise( + "C good select (new connection after failures elsewhere)", + &c.simple(good).await?, + ); + let (lines, _) = server.log_since(0); + println!( + " engine stderr/stdout lines captured with the flag on: {}", + lines.len() + ); + for line in lines.iter().take(4) { + println!(" srv {}", clip(line, 160)); + } + server.child.kill().await?; + Ok(()) +} + +async fn wait_ready(server: &Server) -> Result<(), AnyError> { + let deadline = Instant::now() + Duration::from_secs(30); + loop { + if let Ok((mut raw, _)) = Raw::connect(server.port, &[("user", "stackql")]).await + && let Ok(res) = raw.simple("SHOW VERSION").await + && res.errors.is_empty() + && !res.rows.is_empty() + { + return Ok(()); + } + if Instant::now() > deadline { + return Err("engine did not become ready within 30 s".into()); + } + tokio::time::sleep(Duration::from_millis(25)).await; + } +} + +#[tokio::main] +async fn main() -> Result<(), AnyError> { + let mut bin = + std::env::var_os("STACKQL_BIN").map_or_else(|| PathBuf::from("stackql"), PathBuf::from); + let mut approot = std::env::temp_dir().join("stackql-workbench-spike"); + let mut only: Option = None; + let mut args = std::env::args().skip(1); + while let Some(arg) = args.next() { + match arg.as_str() { + "--bin" => bin = PathBuf::from(args.next().ok_or("--bin needs a value")?), + "--approot" => approot = PathBuf::from(args.next().ok_or("--approot needs a value")?), + "--only" => only = Some(args.next().ok_or("--only needs a value")?), + other => return Err(format!("unknown argument {other}").into()), + } + } + std::fs::create_dir_all(&approot)?; + let wants = |name: &str| only.as_deref().is_none_or(|o| o == name); + + let version = Command::new(&bin).arg("--version").output().await?; + println!( + "engine: {}", + String::from_utf8_lossy(&version.stdout) + .lines() + .next() + .unwrap_or("") + ); + println!("os: {} {}", std::env::consts::OS, std::env::consts::ARCH); + + if wants("readiness") { + section_readiness(&bin, &approot).await?; + } + + let mut server = Server::start(&bin, &approot, &[]).await?; + wait_ready(&server).await?; + println!( + "\nserver for the remaining sections: 127.0.0.1:{}", + server.port + ); + + if wants("handshake") { + section_handshake(&server).await?; + } + if wants("metadata") { + section_metadata(&server).await?; + } + if wants("values") { + section_values(&server).await?; + } + if wants("protocols") { + section_protocols(&server).await?; + } + if wants("errors") { + section_errors(&server).await?; + } + if wants("concurrency") { + section_concurrency(&server).await?; + } + let (lines, _) = server.log_since(0); + println!("\nserver output lines captured in total: {}", lines.len()); + server.child.kill().await?; + + if wants("cancel") { + section_cancel(&bin, &approot).await?; + } + if wants("upstream") { + section_upstream(&bin, &approot).await?; + } + if wants("notices") { + section_notices(&bin, &approot).await?; + } + Ok(()) +} diff --git a/src-tauri/icons/128x128.png b/src-tauri/icons/128x128.png new file mode 100644 index 0000000..c9b0a08 Binary files /dev/null and b/src-tauri/icons/128x128.png differ diff --git a/src-tauri/icons/128x128@2x.png b/src-tauri/icons/128x128@2x.png new file mode 100644 index 0000000..d99632e Binary files /dev/null and b/src-tauri/icons/128x128@2x.png differ diff --git a/src-tauri/icons/32x32.png b/src-tauri/icons/32x32.png new file mode 100644 index 0000000..7a947e4 Binary files /dev/null and b/src-tauri/icons/32x32.png differ diff --git a/src-tauri/icons/64x64.png b/src-tauri/icons/64x64.png new file mode 100644 index 0000000..fe97f91 Binary files /dev/null and b/src-tauri/icons/64x64.png differ diff --git a/src-tauri/icons/icon.icns b/src-tauri/icons/icon.icns new file mode 100644 index 0000000..31a2c7c Binary files /dev/null and b/src-tauri/icons/icon.icns differ diff --git a/src-tauri/icons/icon.ico b/src-tauri/icons/icon.ico new file mode 100644 index 0000000..5cddc46 Binary files /dev/null and b/src-tauri/icons/icon.ico differ diff --git a/src-tauri/icons/icon.png b/src-tauri/icons/icon.png new file mode 100644 index 0000000..3d3055c Binary files /dev/null and b/src-tauri/icons/icon.png differ diff --git a/src-tauri/src/activity/mod.rs b/src-tauri/src/activity/mod.rs new file mode 100644 index 0000000..9421f1f --- /dev/null +++ b/src-tauri/src/activity/mod.rs @@ -0,0 +1,321 @@ +//! What was run, by whom. +//! +//! Every statement executed through either channel is on record: +//! +//! - Statements the operator runs from the editor are appended to a history +//! file by the host. +//! - Everything the agent does is written by the engine to its audit log, +//! which the host reads and never writes. +//! +//! Neither record holds result rows. + +use std::io::Write; +use std::path::{Path, PathBuf}; +use std::sync::Mutex; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::util::lock; + +const MAX_HISTORY_BYTES: u64 = 4 * 1024 * 1024; + +/// One statement the operator ran. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct HistoryEntry { + /// Milliseconds since the Unix epoch. + pub timestamp_ms: u64, + pub sql: String, + /// `ok`, `error` or `abandoned`. + pub outcome: String, + pub rows: Option, + pub elapsed_ms: u64, + pub error: Option, +} + +impl HistoryEntry { + pub fn now(sql: String, outcome: &str, rows: Option, elapsed_ms: u64) -> Self { + Self { + timestamp_ms: now_ms(), + sql, + outcome: outcome.to_string(), + rows, + elapsed_ms, + error: None, + } + } + + pub fn with_error(mut self, error: String) -> Self { + self.error = Some(error); + self + } +} + +fn now_ms() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX)) +} + +/// The operator's statement history, one JSON object per line. +pub struct History { + path: Option, + write: Mutex<()>, +} + +impl History { + pub fn new(path: PathBuf) -> Self { + Self { + path: Some(path), + write: Mutex::new(()), + } + } + + /// A history that records nothing, for tests. + pub fn disabled() -> Self { + Self { + path: None, + write: Mutex::new(()), + } + } + + /// Appends an entry. History is a convenience, so a failure to write it + /// does not fail the statement that was run. + pub fn record(&self, entry: &HistoryEntry) { + let Some(path) = &self.path else { return }; + let Ok(line) = serde_json::to_string(entry) else { + return; + }; + let _guard = lock(&self.write); + if let Some(dir) = path.parent() { + let _ = std::fs::create_dir_all(dir); + } + // Start over when the file gets large. The newest entries are the + // ones that matter. + if std::fs::metadata(path).is_ok_and(|m| m.len() > MAX_HISTORY_BYTES) { + let _ = std::fs::rename(path, path.with_extension("jsonl.old")); + } + if let Ok(mut file) = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(path) + { + let _ = writeln!(file, "{line}"); + } + } + + /// The most recent entries, newest last. + pub fn list(&self, limit: usize) -> Vec { + let Some(path) = &self.path else { + return Vec::new(); + }; + last_lines(path, limit) + .iter() + .filter_map(|line| serde_json::from_str(line).ok()) + .collect() + } +} + +/// One record from the engine's agent audit log, passed through as the +/// engine wrote it. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct AuditRecord { + /// RFC 3339, as written by the engine. + pub timestamp: String, + pub tool: String, + /// The safety mode in effect. + pub mode: String, + /// For example `allow`, `refuse_immediate` or `needs_approval_declined`. + pub decision: String, + pub query_class: String, + pub sql: Option, + pub duration_ms: Option, + pub error: Option, +} + +fn audit_record(value: &Value) -> Option { + let text = |key: &str| value.get(key).and_then(Value::as_str).map(str::to_string); + Some(AuditRecord { + timestamp: text("timestamp")?, + tool: text("tool")?, + mode: text("mode").unwrap_or_default(), + decision: text("decision").unwrap_or_default(), + query_class: text("query_class").unwrap_or_default(), + sql: text("sql"), + duration_ms: value.get("duration_ms").and_then(Value::as_u64), + error: text("error"), + }) +} + +/// Reads the most recent records from the engine's audit log directory, +/// newest last. The engine starts a new file each time it starts, named so +/// that the names sort by time. +pub fn read_audit(dir: &Path, limit: usize) -> Vec { + let Ok(entries) = std::fs::read_dir(dir) else { + return Vec::new(); + }; + let mut files: Vec = entries + .flatten() + .map(|entry| entry.path()) + .filter(|path| path.extension().is_some_and(|ext| ext == "log")) + .collect(); + files.sort(); + + let mut records: Vec = Vec::new(); + for file in files.iter().rev() { + if records.len() >= limit { + break; + } + let mut batch: Vec = last_lines(file, limit - records.len()) + .iter() + .filter_map(|line| serde_json::from_str::(line).ok()) + .filter_map(|value| audit_record(&value)) + .collect(); + // Older files go in front of what has been read so far. + batch.append(&mut records); + records = batch; + } + records +} + +/// The last `limit` non-empty lines of a file, in file order. +fn last_lines(path: &Path, limit: usize) -> Vec { + let Ok(text) = std::fs::read_to_string(path) else { + return Vec::new(); + }; + let lines: Vec<&str> = text.lines().filter(|l| !l.trim().is_empty()).collect(); + let skip = lines.len().saturating_sub(limit); + lines[skip..].iter().map(|l| (*l).to_string()).collect() +} + +/// Both records together, for the activity pane. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Activity { + pub operator: Vec, + pub agent: Vec, +} + +#[cfg(test)] +mod tests { + use super::*; + + fn temp_dir(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("wb-activity-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir + } + + #[test] + fn history_round_trips_and_keeps_order() { + let dir = temp_dir("history"); + let history = History::new(dir.join("history.jsonl")); + history.record(&HistoryEntry::now( + "SHOW PROVIDERS".into(), + "ok", + Some(3), + 4, + )); + history.record( + &HistoryEntry::now("SELEC 1".into(), "error", None, 1).with_error("syntax".into()), + ); + history.record(&HistoryEntry::now( + "SELECT slow".into(), + "abandoned", + None, + 900, + )); + + let entries = history.list(10); + assert_eq!( + entries.iter().map(|e| e.sql.as_str()).collect::>(), + vec!["SHOW PROVIDERS", "SELEC 1", "SELECT slow"] + ); + assert_eq!(entries[0].rows, Some(3)); + assert_eq!(entries[1].error.as_deref(), Some("syntax")); + assert!(entries[0].timestamp_ms > 1_700_000_000_000); + + // The limit keeps the newest. + let last = history.list(2); + assert_eq!(last[0].sql, "SELEC 1"); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn a_missing_history_file_is_an_empty_history() { + let dir = temp_dir("nohistory"); + assert!(History::new(dir.join("none.jsonl")).list(10).is_empty()); + assert!(History::disabled().list(10).is_empty()); + History::disabled().record(&HistoryEntry::now("x".into(), "ok", None, 0)); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn history_entries_serialise_in_camel_case() { + let entry = HistoryEntry { + timestamp_ms: 1, + sql: "SELECT 1".into(), + outcome: "ok".into(), + rows: Some(1), + elapsed_ms: 2, + error: None, + }; + assert_eq!( + serde_json::to_value(&entry).unwrap(), + serde_json::json!({ + "timestampMs": 1, "sql": "SELECT 1", "outcome": "ok", + "rows": 1, "elapsedMs": 2, "error": null + }) + ); + } + + #[test] + fn audit_records_are_read_across_files_newest_last() { + let dir = temp_dir("audit"); + // The real shapes, from docs/spike-mcp.md. + std::fs::write( + dir.join("stackql_mcp_server_20261117T230717Z.log"), + concat!( + r#"{"timestamp":"2026-11-18T10:07:17+11:00","tool":"server_info","mode":"safe","decision":"allow","query_class":"select","duration_ms":0}"#, "\n", + r#"{"timestamp":"2026-11-18T10:07:18+11:00","tool":"run_select_query","mode":"safe","decision":"allow","query_class":"select","sql":"SELECT 1","args":{"row_limit":0,"sql":"SELECT 1"},"duration_ms":12}"#, "\n", + ), + ) + .unwrap(); + std::fs::write( + dir.join("stackql_mcp_server_20261117T230721Z.log"), + concat!( + "not json\n", + r#"{"timestamp":"2026-11-18T10:07:21+11:00","tool":"run_mutation_query","mode":"safe","decision":"needs_approval_declined","query_class":"mutation_delete","sql":"DELETE FROM t","duration_ms":0,"error":"tool \"run_mutation_query\" refused: user declined approval"}"#, "\n", + ), + ) + .unwrap(); + std::fs::write(dir.join("unrelated.txt"), "ignored").unwrap(); + + let records = read_audit(&dir, 10); + assert_eq!( + records.iter().map(|r| r.tool.as_str()).collect::>(), + vec!["server_info", "run_select_query", "run_mutation_query"] + ); + assert_eq!(records[1].sql.as_deref(), Some("SELECT 1")); + assert_eq!(records[1].duration_ms, Some(12)); + assert_eq!(records[2].decision, "needs_approval_declined"); + assert!(records[2].error.as_deref().unwrap().contains("declined")); + + // The limit keeps the newest, across the file boundary. + let last_two = read_audit(&dir, 2); + assert_eq!( + last_two.iter().map(|r| r.tool.as_str()).collect::>(), + vec!["run_select_query", "run_mutation_query"] + ); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn a_missing_audit_directory_is_no_records() { + assert!(read_audit(Path::new("/definitely/not/here"), 10).is_empty()); + } +} diff --git a/src-tauri/src/agent/acp.rs b/src-tauri/src/agent/acp.rs new file mode 100644 index 0000000..c339a64 --- /dev/null +++ b/src-tauri/src/agent/acp.rs @@ -0,0 +1,484 @@ +//! A client for the Agent Client Protocol, version 1, over a byte stream. +//! +//! ACP is JSON-RPC 2.0 with one message per line. An agent the operator +//! installed runs the model and the tools. This side sends prompts, receives +//! what the agent does as notifications, and answers the few requests an +//! agent may make of its client. +//! +//! It is written by hand. The part needed here is small, and the behaviour +//! that matters was observed against a real agent. See `docs/spike-acp.md`. + +use std::collections::HashMap; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; + +use serde_json::{Value, json}; +use tokio::io::{AsyncBufReadExt, AsyncWrite, AsyncWriteExt, BufReader}; +use tokio::sync::{mpsc, oneshot}; + +use crate::connection::{AgentChannel, LogBuffer}; +use crate::util::lock; + +/// The protocol revision this client speaks. +pub const PROTOCOL_VERSION: u64 = 1; + +/// JSON-RPC: the method does not exist. The answer to a request this client +/// does not implement. +pub const METHOD_NOT_FOUND: i64 = -32601; +/// ACP: the agent needs the operator to sign in first. +pub const AUTH_REQUIRED: i64 = -32000; + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum AcpError { + /// The agent answered a request with an error. + #[error("{message}")] + Rpc { code: i64, message: String }, + /// The agent went away. + #[error("The agent closed the connection.")] + Closed, +} + +/// Something the agent sent that is not the answer to a request. +#[derive(Debug, Clone, PartialEq)] +pub enum Incoming { + Notification { + method: String, + params: Value, + }, + /// The agent asks something of its client. It waits for + /// [`AcpClient::respond`] or [`AcpClient::respond_error`]. + Request { + id: Value, + method: String, + params: Value, + }, +} + +type Pending = Arc>>>>; + +pub struct AcpClient { + writer: tokio::sync::Mutex>, + pending: Pending, + next_id: AtomicU64, + closed: Arc, + diagnostics: LogBuffer, + reader: tokio::task::JoinHandle<()>, + /// Keeps the agent process alive. Dropping it ends the agent. + _keepalive: Box, +} + +impl Drop for AcpClient { + fn drop(&mut self) { + self.reader.abort(); + } +} + +impl AcpClient { + /// Starts reading from the channel. Notifications and requests from the + /// agent arrive on the returned receiver, in order. + pub fn connect(channel: AgentChannel) -> (Arc, mpsc::UnboundedReceiver) { + let AgentChannel { + reader, + writer, + diagnostics, + keepalive, + } = channel; + let pending: Pending = Arc::default(); + let closed = Arc::new(AtomicBool::new(false)); + let (incoming_tx, incoming_rx) = mpsc::unbounded_channel(); + + let task = tokio::spawn(read_loop( + reader, + pending.clone(), + closed.clone(), + incoming_tx, + )); + + let client = Arc::new(Self { + writer: tokio::sync::Mutex::new(writer), + pending, + next_id: AtomicU64::new(1), + closed, + diagnostics, + reader: task, + _keepalive: keepalive, + }); + (client, incoming_rx) + } + + pub fn is_closed(&self) -> bool { + self.closed.load(Ordering::SeqCst) + } + + /// The last lines the agent wrote outside the protocol. + pub fn diagnostics_tail(&self, lines: usize) -> Vec { + self.diagnostics.tail(lines) + } + + async fn write(&self, message: &Value) -> Result<(), AcpError> { + if self.is_closed() { + return Err(AcpError::Closed); + } + // serde_json writes no raw newline inside a value, so one message is + // one line, which is what the framing needs. + let mut line = message.to_string(); + line.push('\n'); + let mut writer = self.writer.lock().await; + let sent = async { + writer.write_all(line.as_bytes()).await?; + writer.flush().await + } + .await; + sent.map_err(|_| { + self.closed.store(true, Ordering::SeqCst); + AcpError::Closed + }) + } + + /// Sends a request and waits for its answer, for as long as it takes. A + /// prompt stays open for the whole turn. + pub async fn request(&self, method: &str, params: Value) -> Result { + let id = self.next_id.fetch_add(1, Ordering::SeqCst); + let (tx, rx) = oneshot::channel(); + lock(&self.pending).insert(id, tx); + let message = json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params }); + if let Err(err) = self.write(&message).await { + lock(&self.pending).remove(&id); + return Err(err); + } + rx.await.unwrap_or(Err(AcpError::Closed)) + } + + /// Sends a notification. There is no answer to wait for. + pub async fn notify(&self, method: &str, params: Value) -> Result<(), AcpError> { + self.write(&json!({ "jsonrpc": "2.0", "method": method, "params": params })) + .await + } + + /// Answers a request from the agent. + pub async fn respond(&self, id: Value, result: Value) -> Result<(), AcpError> { + self.write(&json!({ "jsonrpc": "2.0", "id": id, "result": result })) + .await + } + + /// Refuses a request from the agent. + pub async fn respond_error(&self, id: Value, code: i64, message: &str) -> Result<(), AcpError> { + self.write(&json!({ + "jsonrpc": "2.0", + "id": id, + "error": { "code": code, "message": message } + })) + .await + } +} + +async fn read_loop( + reader: Box, + pending: Pending, + closed: Arc, + incoming: mpsc::UnboundedSender, +) { + let mut lines = BufReader::new(reader).lines(); + while let Ok(Some(line)) = lines.next_line().await { + let line = line.trim(); + if line.is_empty() { + continue; + } + // Anything that is not a JSON object is not protocol. Skip it and + // keep going: one stray line must not end the session. + let Ok(Value::Object(mut message)) = serde_json::from_str::(line) else { + continue; + }; + let id = message.remove("id").filter(|id| !id.is_null()); + if let Some(Value::String(method)) = message.remove("method") { + let params = message.remove("params").unwrap_or(Value::Null); + let item = match id { + Some(id) => Incoming::Request { id, method, params }, + None => Incoming::Notification { method, params }, + }; + if incoming.send(item).is_err() { + break; + } + continue; + } + // No method, so it is the answer to one of our requests. + let Some(waiter) = id + .as_ref() + .and_then(Value::as_u64) + .and_then(|id| lock(&pending).remove(&id)) + else { + continue; + }; + let outcome = match message.remove("error") { + Some(error) => Err(AcpError::Rpc { + code: error.get("code").and_then(Value::as_i64).unwrap_or(0), + message: error + .get("message") + .and_then(Value::as_str) + .unwrap_or("The agent reported an error without a message.") + .to_string(), + }), + None => Ok(message.remove("result").unwrap_or(Value::Null)), + }; + let _ = waiter.send(outcome); + } + + // The stream ended. Nothing that is waiting will get an answer now. + closed.store(true, Ordering::SeqCst); + let waiting: Vec<_> = lock(&pending).drain().collect(); + for (_, waiter) in waiting { + let _ = waiter.send(Err(AcpError::Closed)); + } +} + +#[cfg(test)] +pub(crate) mod testing { + //! A scripted agent on the other end of an in-memory stream. + + use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader, DuplexStream, ReadHalf, WriteHalf}; + + use super::*; + + pub struct FakeAgent { + lines: tokio::io::Lines>>, + writer: WriteHalf, + } + + /// A connected client and the agent it talks to. + pub fn pair() -> (Arc, mpsc::UnboundedReceiver, FakeAgent) { + let (ours, theirs) = tokio::io::duplex(1 << 16); + let (our_read, our_write) = tokio::io::split(ours); + let (client, incoming) = AcpClient::connect(AgentChannel { + reader: Box::new(our_read), + writer: Box::new(our_write), + diagnostics: LogBuffer::default(), + keepalive: Box::new(()), + }); + (client, incoming, FakeAgent::over(theirs)) + } + + impl FakeAgent { + /// An agent on one end of an in-memory stream. + pub fn over(stream: DuplexStream) -> Self { + let (read, write) = tokio::io::split(stream); + Self { + lines: BufReader::new(read).lines(), + writer: write, + } + } + + /// The next message the client sent. + pub async fn receive(&mut self) -> Value { + let line = self + .lines + .next_line() + .await + .expect("read from client") + .expect("client closed"); + serde_json::from_str(&line).expect("client sent JSON") + } + + /// Receives a request for `method` and returns its id and params. + pub async fn expect(&mut self, method: &str) -> (Value, Value) { + let message = self.receive().await; + assert_eq!(message["method"], method, "unexpected message {message}"); + (message["id"].clone(), message["params"].clone()) + } + + pub async fn send(&mut self, message: Value) { + let mut line = message.to_string(); + line.push('\n'); + self.writer.write_all(line.as_bytes()).await.expect("write"); + } + + pub async fn send_raw(&mut self, text: &str) { + self.writer.write_all(text.as_bytes()).await.expect("write"); + } + + pub async fn result(&mut self, id: Value, result: Value) { + self.send(json!({ "jsonrpc": "2.0", "id": id, "result": result })) + .await; + } + + pub async fn error(&mut self, id: Value, code: i64, message: &str) { + self.send(json!({ + "jsonrpc": "2.0", + "id": id, + "error": { "code": code, "message": message } + })) + .await; + } + + pub async fn update(&mut self, session: &str, update: Value) { + self.send(json!({ + "jsonrpc": "2.0", + "method": "session/update", + "params": { "sessionId": session, "update": update } + })) + .await; + } + } +} + +#[cfg(test)] +mod tests { + use super::testing::pair; + use super::*; + + #[tokio::test] + async fn a_request_gets_its_own_answer() { + let (client, _incoming, mut agent) = pair(); + let asking = tokio::spawn({ + let client = client.clone(); + async move { + client + .request("initialize", json!({ "protocolVersion": 1 })) + .await + } + }); + + let (id, params) = agent.expect("initialize").await; + assert_eq!(params["protocolVersion"], 1); + agent.result(id, json!({ "protocolVersion": 1 })).await; + + let answer = asking.await.unwrap().unwrap(); + assert_eq!(answer["protocolVersion"], 1); + } + + #[tokio::test] + async fn answers_are_matched_by_id_not_by_order() { + let (client, _incoming, mut agent) = pair(); + let first = tokio::spawn({ + let client = client.clone(); + async move { client.request("a", Value::Null).await } + }); + let (first_id, _) = agent.expect("a").await; + let second = tokio::spawn({ + let client = client.clone(); + async move { client.request("b", Value::Null).await } + }); + let (second_id, _) = agent.expect("b").await; + + agent.result(second_id, json!("for b")).await; + agent.result(first_id, json!("for a")).await; + + assert_eq!(first.await.unwrap().unwrap(), json!("for a")); + assert_eq!(second.await.unwrap().unwrap(), json!("for b")); + } + + #[tokio::test] + async fn an_error_answer_carries_its_code_and_message() { + let (client, _incoming, mut agent) = pair(); + let asking = tokio::spawn({ + let client = client.clone(); + async move { client.request("session/new", json!({})).await } + }); + let (id, _) = agent.expect("session/new").await; + agent + .error(id, AUTH_REQUIRED, "Authentication required") + .await; + + assert_eq!( + asking.await.unwrap().unwrap_err(), + AcpError::Rpc { + code: AUTH_REQUIRED, + message: "Authentication required".to_string() + } + ); + } + + #[tokio::test] + async fn notifications_and_requests_from_the_agent_arrive_in_order() { + let (client, mut incoming, mut agent) = pair(); + agent + .update("s1", json!({ "sessionUpdate": "agent_message_chunk" })) + .await; + agent + .send(json!({ + "jsonrpc": "2.0", + "id": 0, + "method": "session/request_permission", + "params": { "sessionId": "s1" } + })) + .await; + + match incoming.recv().await.unwrap() { + Incoming::Notification { method, params } => { + assert_eq!(method, "session/update"); + assert_eq!(params["sessionId"], "s1"); + } + other => panic!("expected a notification, got {other:?}"), + } + let Incoming::Request { id, method, .. } = incoming.recv().await.unwrap() else { + panic!("expected a request"); + }; + assert_eq!(method, "session/request_permission"); + // Id 0 is a real id. It must not be mistaken for "no id". + assert_eq!(id, json!(0)); + + client + .respond(id, json!({ "outcome": { "outcome": "cancelled" } })) + .await + .unwrap(); + let answer = agent.receive().await; + assert_eq!(answer["id"], 0); + assert_eq!(answer["result"]["outcome"]["outcome"], "cancelled"); + } + + #[tokio::test] + async fn an_unsupported_request_can_be_refused() { + let (client, _incoming, mut agent) = pair(); + client + .respond_error(json!(7), METHOD_NOT_FOUND, "Method not found") + .await + .unwrap(); + let answer = agent.receive().await; + assert_eq!(answer["id"], 7); + assert_eq!(answer["error"]["code"], METHOD_NOT_FOUND); + } + + #[tokio::test] + async fn lines_that_are_not_protocol_are_skipped() { + let (client, mut incoming, mut agent) = pair(); + agent.send_raw("some banner text\n\n[1, 2]\n").await; + agent + .send(json!({ "jsonrpc": "2.0", "method": "ping", "params": {} })) + .await; + match incoming.recv().await.unwrap() { + Incoming::Notification { method, .. } => assert_eq!(method, "ping"), + other => panic!("expected the notification, got {other:?}"), + } + assert!(!client.is_closed()); + } + + #[tokio::test] + async fn every_message_is_one_line_even_with_newlines_in_the_text() { + let (client, _incoming, mut agent) = pair(); + client + .notify("session/cancel", json!({ "note": "line one\nline two" })) + .await + .unwrap(); + let message = agent.receive().await; + assert_eq!(message["params"]["note"], "line one\nline two"); + assert!(message.get("id").is_none(), "a notification has no id"); + } + + #[tokio::test] + async fn the_agent_going_away_fails_what_is_waiting() { + let (client, mut incoming, mut agent) = pair(); + let asking = tokio::spawn({ + let client = client.clone(); + async move { client.request("session/prompt", json!({})).await } + }); + agent.expect("session/prompt").await; + drop(agent); + + assert_eq!(asking.await.unwrap().unwrap_err(), AcpError::Closed); + assert!(incoming.recv().await.is_none()); + assert!(client.is_closed()); + assert_eq!( + client.request("session/prompt", json!({})).await, + Err(AcpError::Closed) + ); + } +} diff --git a/src-tauri/src/agent/approvals.rs b/src-tauri/src/agent/approvals.rs new file mode 100644 index 0000000..2337db2 --- /dev/null +++ b/src-tauri/src/agent/approvals.rs @@ -0,0 +1,262 @@ +//! Approval requests: the client side of the engine's approval flow. +//! +//! The engine decides what needs approval and asks through MCP elicitation. +//! This module only carries the question to the operator and the answer +//! back. It never answers on its own. There is no host-side rule about which +//! statements are safe, because the engine owns that decision. + +use std::collections::HashMap; +use std::sync::Mutex; +use std::sync::atomic::{AtomicU64, Ordering}; + +use serde::{Deserialize, Serialize}; +use tokio::sync::oneshot; + +use crate::util::lock; + +/// What the operator is asked to approve. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct ApprovalRequest { + pub id: String, + /// The engine's message, exactly as sent. + pub message: String, + /// The tool the model called, when the message names one. + pub tool: Option, + /// The engine's classification, for example `mutation_delete`. + pub query_class: Option, + /// The exact SQL, when the message carries it. + pub sql: Option, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum ApprovalDecision { + Accept, + Decline, + /// The prompt went away without an answer, for example because the + /// operator stopped the turn. + Cancel, +} + +type Listener = Box; + +#[derive(Default)] +pub struct Approvals { + pending: Mutex>>, + listener: Mutex>, + next: AtomicU64, +} + +impl Approvals { + /// Sets who is shown new requests. With nobody listening a request is + /// declined, because there is nobody to ask. + pub fn set_listener(&self, listener: Option) { + *lock(&self.listener) = listener; + } + + /// Asks the operator and waits for the answer, however long it takes. + pub async fn ask(&self, message: String) -> ApprovalDecision { + let id = format!("approval-{}", self.next.fetch_add(1, Ordering::SeqCst) + 1); + let (tx, rx) = oneshot::channel(); + lock(&self.pending).insert(id.clone(), tx); + + let request = parse_request(id.clone(), message); + let shown = match lock(&self.listener).as_ref() { + Some(listener) => { + listener(request); + true + } + None => false, + }; + if !shown { + lock(&self.pending).remove(&id); + return ApprovalDecision::Decline; + } + // The sender is dropped only if the request is discarded unanswered. + rx.await.unwrap_or(ApprovalDecision::Cancel) + } + + /// Delivers the operator's answer. Returns false if there is no such + /// request, for example because it was already answered. + pub fn resolve(&self, id: &str, decision: ApprovalDecision) -> bool { + match lock(&self.pending).remove(id) { + Some(tx) => tx.send(decision).is_ok(), + None => false, + } + } + + /// Cancels every request that is still waiting. + pub fn cancel_all(&self) { + let waiting: Vec<_> = lock(&self.pending).drain().collect(); + for (_, tx) in waiting { + let _ = tx.send(ApprovalDecision::Cancel); + } + } + + pub fn pending_count(&self) -> usize { + lock(&self.pending).len() + } +} + +/// Reads the tool, the class and the SQL out of the engine's message. +/// +/// The message looks like this: +/// +/// ```text +/// Approve run_mutation_query (mutation_delete)? +/// +/// SQL: DELETE FROM ... +/// ``` +/// +/// The whole message is always shown as well, so nothing is lost if the +/// wording changes and these fields come back empty. +fn parse_request(id: String, message: String) -> ApprovalRequest { + let first_line = message.lines().next().unwrap_or_default(); + let (tool, query_class) = first_line + .strip_prefix("Approve ") + .and_then(|rest| rest.strip_suffix('?')) + .map(|rest| match rest.split_once(" (") { + Some((tool, class)) => ( + Some(tool.trim().to_string()), + class.strip_suffix(')').map(|c| c.trim().to_string()), + ), + None => (Some(rest.trim().to_string()), None), + }) + .unwrap_or((None, None)); + let sql = message + .split_once("\nSQL: ") + .map(|(_, sql)| sql.trim().to_string()) + .filter(|sql| !sql.is_empty()); + ApprovalRequest { + id, + message, + tool: tool.filter(|t| !t.is_empty()), + query_class: query_class.filter(|c| !c.is_empty()), + sql, + } +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use super::*; + + const MESSAGE: &str = "Approve run_mutation_query (mutation_delete)?\n\nSQL: DELETE FROM github.repos.repos WHERE owner = 'x' AND repo = 'y'"; + + fn listening(approvals: &Approvals) -> Arc>> { + let seen: Arc>> = Arc::default(); + let sink = seen.clone(); + approvals.set_listener(Some(Box::new(move |request| { + sink.lock().unwrap().push(request); + }))); + seen + } + + #[test] + fn the_engine_message_is_parsed() { + let request = parse_request("a-1".into(), MESSAGE.into()); + assert_eq!(request.tool.as_deref(), Some("run_mutation_query")); + assert_eq!(request.query_class.as_deref(), Some("mutation_delete")); + assert_eq!( + request.sql.as_deref(), + Some("DELETE FROM github.repos.repos WHERE owner = 'x' AND repo = 'y'") + ); + assert_eq!(request.message, MESSAGE); + } + + #[test] + fn multi_line_sql_is_kept_whole() { + let request = parse_request( + "a-1".into(), + "Approve run_mutation_query (mutation_create)?\n\nSQL: INSERT INTO t\nSELECT 1,\n 2" + .into(), + ); + assert_eq!( + request.sql.as_deref(), + Some("INSERT INTO t\nSELECT 1,\n 2") + ); + } + + #[test] + fn an_unfamiliar_message_still_carries_its_text() { + let request = parse_request("a-1".into(), "Do you want to proceed?".into()); + assert_eq!(request.tool, None); + assert_eq!(request.query_class, None); + assert_eq!(request.sql, None); + assert_eq!(request.message, "Do you want to proceed?"); + } + + #[tokio::test] + async fn a_request_waits_for_the_operator() { + let approvals = Arc::new(Approvals::default()); + let seen = listening(&approvals); + + let asking = approvals.clone(); + let task = tokio::spawn(async move { asking.ask(MESSAGE.into()).await }); + + // Nothing is decided until the operator answers. + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + assert!(!task.is_finished()); + assert_eq!(approvals.pending_count(), 1); + + let id = seen.lock().unwrap()[0].id.clone(); + assert!(approvals.resolve(&id, ApprovalDecision::Accept)); + assert_eq!(task.await.unwrap(), ApprovalDecision::Accept); + assert_eq!(approvals.pending_count(), 0); + } + + #[tokio::test] + async fn with_nobody_listening_the_answer_is_decline() { + let approvals = Approvals::default(); + assert_eq!( + approvals.ask(MESSAGE.into()).await, + ApprovalDecision::Decline + ); + assert_eq!(approvals.pending_count(), 0); + } + + #[tokio::test] + async fn cancelling_answers_every_waiting_request() { + let approvals = Arc::new(Approvals::default()); + let _seen = listening(&approvals); + let a = approvals.clone(); + let b = approvals.clone(); + let first = tokio::spawn(async move { a.ask("one".into()).await }); + let second = tokio::spawn(async move { b.ask("two".into()).await }); + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + + approvals.cancel_all(); + + assert_eq!(first.await.unwrap(), ApprovalDecision::Cancel); + assert_eq!(second.await.unwrap(), ApprovalDecision::Cancel); + } + + #[tokio::test] + async fn an_answer_is_accepted_once() { + let approvals = Arc::new(Approvals::default()); + let seen = listening(&approvals); + let asking = approvals.clone(); + let task = tokio::spawn(async move { asking.ask(MESSAGE.into()).await }); + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + let id = seen.lock().unwrap()[0].id.clone(); + + assert!(approvals.resolve(&id, ApprovalDecision::Decline)); + assert!(!approvals.resolve(&id, ApprovalDecision::Accept)); + assert!(!approvals.resolve("no-such-id", ApprovalDecision::Accept)); + assert_eq!(task.await.unwrap(), ApprovalDecision::Decline); + } + + #[test] + fn decisions_serialise_in_camel_case() { + assert_eq!( + serde_json::to_value(ApprovalDecision::Accept).unwrap(), + serde_json::json!("accept") + ); + assert_eq!( + serde_json::from_value::(serde_json::json!("decline")).unwrap(), + ApprovalDecision::Decline + ); + } +} diff --git a/src-tauri/src/agent/backend.rs b/src-tauri/src/agent/backend.rs new file mode 100644 index 0000000..be1d17a --- /dev/null +++ b/src-tauri/src/agent/backend.rs @@ -0,0 +1,344 @@ +//! The seam between the agent loop and a model. +//! +//! Everything above this trait is the same for every backend: the loop, the +//! MCP client, the approval flow and the chat UI. A backend only turns a +//! conversation into one request to its provider and the reply back into +//! text and tool calls. + +use futures_util::future::BoxFuture; +use serde::{Deserialize, Serialize}; +use serde_json::{Map, Value}; + +/// A tool the model may call. The schema comes from the MCP server and is +/// passed through unchanged. +#[derive(Debug, Clone, PartialEq)] +pub struct ToolSpec { + pub name: String, + pub description: String, + /// JSON Schema for the arguments. + pub input_schema: Value, + /// Whether the tool can make a destructive change, in the server's own + /// words: its `destructiveHint`. `None` when the server does not say. + /// The host does not work this out for itself. + pub destructive: Option, +} + +/// A tool call the model asked for. +#[derive(Debug, Clone, PartialEq)] +pub struct ToolCall { + /// Identifies the call so its result can be matched to it. + pub id: String, + pub name: String, + pub arguments: Map, +} + +/// What a tool call produced, as the model will see it. +#[derive(Debug, Clone, PartialEq)] +pub struct ToolOutcome { + pub call_id: String, + pub name: String, + pub content: String, + pub is_error: bool, +} + +/// One turn of the conversation, in a shape every backend can translate. +#[derive(Debug, Clone, PartialEq)] +pub enum Message { + User { + text: String, + }, + Assistant { + text: String, + tool_calls: Vec, + /// The provider's own representation of this turn. A backend sends + /// it back as it was, because some providers attach state to their + /// replies that must be returned untouched. Only the backend that + /// produced it may interpret it. + raw: Option, + }, + ToolResults { + results: Vec, + }, +} + +pub struct ChatRequest<'a> { + pub system: &'a str, + pub messages: &'a [Message], + pub tools: &'a [ToolSpec], +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase", tag = "kind", content = "detail")] +pub enum StopReason { + /// The model finished its answer. + EndTurn, + /// The model wants tools run. + ToolUse, + /// The reply was cut off by the output limit. + MaxTokens, + /// The provider declined to answer. + Refused(String), + Other(String), +} + +/// What a call to a model, or a whole turn, used. Each count is `None` when +/// the provider did not report it, which is not the same as zero. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Usage { + /// Everything the model was sent, whether or not the provider read part + /// of it from its cache. + pub input_tokens: Option, + /// Everything the model wrote, its thinking included where the provider + /// counts that apart. + pub output_tokens: Option, + /// The part of the input the provider read from its cache, which it + /// bills at a lower rate. Already counted in `input_tokens`. + pub cached_input_tokens: Option, +} + +impl Usage { + /// Adds the use of one call to a running total. A count stays `None` + /// until some call reports it. + pub fn plus(self, other: Self) -> Self { + let add = |a: Option, b: Option| match (a, b) { + (None, None) => None, + (a, b) => Some(a.unwrap_or(0) + b.unwrap_or(0)), + }; + Self { + input_tokens: add(self.input_tokens, other.input_tokens), + output_tokens: add(self.output_tokens, other.output_tokens), + cached_input_tokens: add(self.cached_input_tokens, other.cached_input_tokens), + } + } +} + +#[derive(Debug, Clone, PartialEq)] +pub struct ChatResponse { + pub text: String, + pub tool_calls: Vec, + pub raw: Option, + pub stop: StopReason, + pub usage: Usage, +} + +impl ChatResponse { + /// The assistant turn to append to the conversation. + pub fn into_message(self) -> Message { + Message::Assistant { + text: self.text, + tool_calls: self.tool_calls, + raw: self.raw, + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum InferenceError { + #[error("The inference provider rejected the API key. Check it in Settings. ({0})")] + Auth(String), + #[error("The inference provider is rate limiting or out of quota. ({0})")] + RateLimited(String), + #[error("The inference provider is unavailable. Try again shortly. ({0})")] + Unavailable(String), + #[error("The inference provider rejected the request. ({0})")] + InvalidRequest(String), + #[error("Could not reach the inference provider. ({0})")] + Network(String), + #[error("The inference provider sent a reply that could not be read. ({0})")] + Protocol(String), +} + +/// Which family of API a backend speaks. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum BackendKind { + Gemini, + Anthropic, + /// OpenAI's Chat Completions API, and any server that implements it, + /// which covers local inference. + OpenaiCompatible, + /// The GitHub Copilot CLI, driven as a delegated agent. It runs the + /// model with the operator's own sign-in, which this app never sees. + GithubCopilot, +} + +impl BackendKind { + /// Every backend, in the order the settings pane lists them. + pub const ALL: [Self; 4] = [ + Self::Gemini, + Self::Anthropic, + Self::OpenaiCompatible, + Self::GithubCopilot, + ]; + + /// The name the API key is stored under in the OS keychain. `None` for + /// a backend that has no key of ours to store. + pub fn secret_name(self) -> Option<&'static str> { + match self { + Self::Gemini => Some("inference.gemini.api_key"), + Self::Anthropic => Some("inference.anthropic.api_key"), + Self::OpenaiCompatible => Some("inference.openai_compatible.api_key"), + Self::GithubCopilot => None, + } + } + + /// Whether the backend can work without an API key. A local server + /// usually has none, and a delegated agent signs in by itself. + pub fn key_optional(self) -> bool { + matches!(self, Self::OpenaiCompatible | Self::GithubCopilot) + } + + /// Whether an agent the operator installed runs the model and the + /// tools, instead of the host's own loop. + pub fn is_delegated(self) -> bool { + matches!(self, Self::GithubCopilot) + } +} + +pub trait InferenceBackend: Send + Sync { + /// Sends the conversation to the model and returns its next turn. + fn complete<'a>( + &'a self, + request: ChatRequest<'a>, + ) -> BoxFuture<'a, Result>; +} + +/// Turns an HTTP failure into the matching error. Shared by the backends, +/// which differ only in how they dig a message out of the body. +pub fn classify_http_error(status: u16, message: String) -> InferenceError { + match status { + 401 | 403 => InferenceError::Auth(message), + 402 | 429 => InferenceError::RateLimited(message), + 408 | 500..=599 => InferenceError::Unavailable(message), + _ => InferenceError::InvalidRequest(message), + } +} + +/// Turns a transport failure into an error. The text never includes the +/// request, so a key in a header cannot leak into it. +pub fn classify_transport_error(err: &reqwest::Error) -> InferenceError { + let what = if err.is_timeout() { + "the request timed out" + } else if err.is_connect() { + "could not connect" + } else if err.is_decode() || err.is_body() { + "the reply was not readable" + } else { + "the request failed" + }; + InferenceError::Network(what.to_string()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn usage_adds_up_across_the_calls_of_a_turn() { + let total = Usage { + input_tokens: Some(10), + output_tokens: None, + cached_input_tokens: None, + } + .plus(Usage { + input_tokens: Some(5), + output_tokens: Some(7), + cached_input_tokens: Some(4), + }); + assert_eq!(total.input_tokens, Some(15)); + assert_eq!(total.output_tokens, Some(7)); + assert_eq!(total.cached_input_tokens, Some(4)); + // What no call reported stays unknown. It does not become zero. + assert_eq!(Usage::default().plus(Usage::default()), Usage::default()); + } + + #[test] + fn usage_crosses_to_the_webview_in_camel_case() { + let usage = Usage { + input_tokens: Some(19_353), + output_tokens: Some(92), + cached_input_tokens: None, + }; + assert_eq!( + serde_json::to_value(usage).unwrap(), + serde_json::json!({ "inputTokens": 19353, "outputTokens": 92, "cachedInputTokens": null }) + ); + } + + #[test] + fn http_statuses_map_to_the_right_error() { + assert!(matches!( + classify_http_error(401, "x".into()), + InferenceError::Auth(_) + )); + assert!(matches!( + classify_http_error(403, "x".into()), + InferenceError::Auth(_) + )); + assert!(matches!( + classify_http_error(429, "x".into()), + InferenceError::RateLimited(_) + )); + assert!(matches!( + classify_http_error(503, "x".into()), + InferenceError::Unavailable(_) + )); + assert!(matches!( + classify_http_error(400, "x".into()), + InferenceError::InvalidRequest(_) + )); + assert!(matches!( + classify_http_error(404, "x".into()), + InferenceError::InvalidRequest(_) + )); + } + + #[test] + fn backend_kinds_serialise_in_snake_case() { + assert_eq!( + serde_json::to_value(BackendKind::OpenaiCompatible).unwrap(), + serde_json::json!("openai_compatible") + ); + assert_eq!( + serde_json::from_value::(serde_json::json!("gemini")).unwrap(), + BackendKind::Gemini + ); + } + + #[test] + fn each_backend_has_its_own_keychain_entry() { + let names = [ + BackendKind::Gemini.secret_name(), + BackendKind::Anthropic.secret_name(), + BackendKind::OpenaiCompatible.secret_name(), + ]; + assert_eq!( + names.iter().collect::>().len(), + 3 + ); + assert!(names.iter().all(Option::is_some)); + assert!(BackendKind::OpenaiCompatible.key_optional()); + assert!(!BackendKind::Gemini.key_optional()); + } + + #[test] + fn a_delegated_agent_has_no_key_of_ours() { + let kind = BackendKind::GithubCopilot; + assert!(kind.is_delegated()); + assert_eq!(kind.secret_name(), None); + assert!(kind.key_optional()); + assert_eq!( + serde_json::to_value(kind).unwrap(), + serde_json::json!("github_copilot") + ); + for other in [ + BackendKind::Gemini, + BackendKind::Anthropic, + BackendKind::OpenaiCompatible, + ] { + assert!(!other.is_delegated()); + } + assert_eq!(BackendKind::ALL.len(), 4); + } +} diff --git a/src-tauri/src/agent/backends/anthropic.rs b/src-tauri/src/agent/backends/anthropic.rs new file mode 100644 index 0000000..c1dfe07 --- /dev/null +++ b/src-tauri/src/agent/backends/anthropic.rs @@ -0,0 +1,598 @@ +//! Claude, through the Anthropic Messages API, with an API key. +//! +//! There is no official Anthropic SDK for Rust, so this speaks the REST API +//! directly. Wire format notes, from Anthropic's API reference as read in +//! November 2026: +//! +//! - `POST {base}/v1/messages` with `x-api-key` and `anthropic-version`. +//! - Tools are `{ name, description, input_schema }`. The MCP tool schemas +//! pass unchanged. +//! - The reply is a list of content blocks. `tool_use` blocks are the tool +//! calls. Thinking blocks must go back exactly as they came, so the whole +//! list is kept and returned untouched. +//! - Every result for one assistant turn goes back in a single `user` +//! message, as `tool_result` blocks. +//! - No sampling parameters and no thinking configuration are sent. Current +//! models reject the former and choose the latter themselves, and leaving +//! both out works on every model an operator might pick. +//! - A request can be declined: HTTP 200 with `stop_reason: "refusal"`. + +use futures_util::FutureExt; +use futures_util::future::BoxFuture; +use serde_json::{Map, Value, json}; + +use super::post_json; +use crate::agent::backend::{ + ChatRequest, ChatResponse, InferenceBackend, InferenceError, Message, StopReason, ToolCall, + Usage, +}; + +pub const DEFAULT_BASE_URL: &str = "https://api.anthropic.com"; +pub const DEFAULT_MODEL: &str = "claude-opus-5-5"; + +const API_VERSION: &str = "2026-10-21"; +/// Kept below the size at which a non-streaming request risks a timeout. +const MAX_TOKENS: u32 = 16_000; + +/// Server-side fallback: when one of these models declines a request on +/// policy grounds, the API reruns it on a fallback model inside the same +/// call. It is opt-in per request, and only these models take it. +const FALLBACK_BETA: &str = "server-side-fallback-2026-07-01"; +const MODELS_WITH_FALLBACK: [&str; 5] = [ + "claude-fable-5-2", + "claude-fable-5-1", + "claude-opus-5-5", + "claude-opus-5", + "claude-sonnet-5-5", +]; + +pub struct Anthropic { + http: reqwest::Client, + base_url: String, + model: String, + api_key: String, +} + +impl Anthropic { + pub fn new(http: reqwest::Client, base_url: String, model: String, api_key: String) -> Self { + Self { + http, + base_url, + model, + api_key, + } + } +} + +impl InferenceBackend for Anthropic { + fn complete<'a>( + &'a self, + request: ChatRequest<'a>, + ) -> BoxFuture<'a, Result> { + async move { + let body = build_request(&self.model, &request); + let mut headers = vec![ + ("x-api-key", self.api_key.as_str()), + ("anthropic-version", API_VERSION), + ]; + if uses_fallback(&self.model) { + headers.push(("anthropic-beta", FALLBACK_BETA)); + } + let reply = post_json( + &self.http, + &format!("{}/v1/messages", self.base_url), + &headers, + &body, + error_message, + ) + .await?; + parse_response(&reply) + } + .boxed() + } +} + +fn uses_fallback(model: &str) -> bool { + MODELS_WITH_FALLBACK.contains(&model) +} + +fn error_message(body: &Value) -> Option { + let error = body.get("error")?; + let message = error.get("message")?.as_str()?; + let kind = error.get("type").and_then(Value::as_str).unwrap_or(""); + Some( + format!("{kind}: {message}") + .trim_start_matches(": ") + .to_string(), + ) +} + +pub fn build_request(model: &str, request: &ChatRequest<'_>) -> Value { + let mut body = Map::new(); + body.insert("model".into(), json!(model)); + body.insert("max_tokens".into(), json!(MAX_TOKENS)); + // Caches the longest stable prefix: tools, system text and the + // conversation so far. Each step of a turn resends all of that. + body.insert("cache_control".into(), json!({ "type": "ephemeral" })); + if !request.system.is_empty() { + body.insert("system".into(), json!(request.system)); + } + if !request.tools.is_empty() { + let tools: Vec = request + .tools + .iter() + .map(|tool| { + json!({ + "name": tool.name, + "description": tool.description, + "input_schema": tool.input_schema, + }) + }) + .collect(); + body.insert("tools".into(), Value::Array(tools)); + } + if uses_fallback(model) { + body.insert("fallbacks".into(), json!("default")); + } + body.insert( + "messages".into(), + Value::Array(request.messages.iter().map(message_of).collect()), + ); + Value::Object(body) +} + +fn message_of(message: &Message) -> Value { + match message { + Message::User { text } => json!({ "role": "user", "content": text }), + // The model's content goes back exactly as it arrived. Thinking + // blocks in it are only valid unchanged. + Message::Assistant { raw: Some(raw), .. } => { + json!({ "role": "assistant", "content": raw }) + } + Message::Assistant { + text, tool_calls, .. + } => { + let mut content = Vec::new(); + if !text.is_empty() { + content.push(json!({ "type": "text", "text": text })); + } + for call in tool_calls { + content.push(json!({ + "type": "tool_use", + "id": call.id, + "name": call.name, + "input": call.arguments, + })); + } + if content.is_empty() { + content.push(json!({ "type": "text", "text": "(no reply)" })); + } + json!({ "role": "assistant", "content": content }) + } + // One user message holds every result. Splitting them across + // messages teaches the model to stop calling tools in parallel. + Message::ToolResults { results } => { + let content: Vec = results + .iter() + .map(|result| { + let mut block = json!({ + "type": "tool_result", + "tool_use_id": result.call_id, + "content": result.content, + }); + if result.is_error { + block["is_error"] = json!(true); + } + block + }) + .collect(); + json!({ "role": "user", "content": content }) + } + } +} + +pub fn parse_response(reply: &Value) -> Result { + let blocks = reply + .get("content") + .and_then(Value::as_array) + .ok_or_else(|| InferenceError::Protocol("the reply had no content list".into()))?; + + let mut text = String::new(); + let mut tool_calls = Vec::new(); + for block in blocks { + match block.get("type").and_then(Value::as_str) { + Some("text") => { + if let Some(piece) = block.get("text").and_then(Value::as_str) { + text.push_str(piece); + } + } + Some("tool_use") => { + let id = block.get("id").and_then(Value::as_str); + let name = block.get("name").and_then(Value::as_str); + let (Some(id), Some(name)) = (id, name) else { + return Err(InferenceError::Protocol( + "a tool call had no id or no name".into(), + )); + }; + tool_calls.push(ToolCall { + id: id.to_string(), + name: name.to_string(), + arguments: block + .get("input") + .and_then(Value::as_object) + .cloned() + .unwrap_or_default(), + }); + } + // Thinking and other block kinds are kept in the raw reply and + // are not shown as answer text. + _ => {} + } + } + + // Check why the model stopped before trusting the content. + let stop = match reply.get("stop_reason").and_then(Value::as_str) { + Some("refusal") => { + let detail = reply + .pointer("/stop_details/explanation") + .and_then(Value::as_str) + .or_else(|| { + reply + .pointer("/stop_details/category") + .and_then(Value::as_str) + }) + .unwrap_or("no reason given"); + StopReason::Refused(format!("The model declined this request: {detail}")) + } + Some("tool_use") => StopReason::ToolUse, + Some("end_turn" | "stop_sequence") | None => StopReason::EndTurn, + Some("max_tokens") => StopReason::MaxTokens, + Some(other) => StopReason::Other(other.to_string()), + }; + // A declined reply may still list tool calls. They must not run. + if matches!(stop, StopReason::Refused(_)) { + tool_calls.clear(); + } + + let count = |name: &str| { + reply + .pointer(&format!("/usage/{name}")) + .and_then(Value::as_u64) + }; + // Cached input is reported apart from uncached input. The total is what + // the operator cares about. + let input_parts = [ + count("input_tokens"), + count("cache_creation_input_tokens"), + count("cache_read_input_tokens"), + ]; + let usage = Usage { + input_tokens: input_parts + .iter() + .any(Option::is_some) + .then(|| input_parts.iter().flatten().sum()), + output_tokens: count("output_tokens"), + cached_input_tokens: count("cache_read_input_tokens"), + }; + + Ok(ChatResponse { + text, + tool_calls, + raw: (!blocks.is_empty()).then(|| Value::Array(blocks.clone())), + stop, + usage, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::agent::backend::{ToolOutcome, ToolSpec}; + use crate::agent::backends::testing::serve_once; + + fn tools() -> Vec { + vec![ToolSpec { + name: "run_select_query".into(), + description: "Execute a SELECT.".into(), + input_schema: json!({ + "type": "object", + "additionalProperties": false, + "properties": { "sql": { "type": "string" } }, + "required": ["sql"] + }), + destructive: Some(false), + }] + } + + #[test] + fn the_request_has_the_expected_shape() { + let messages = vec![Message::User { + text: "list providers".into(), + }]; + let tools = tools(); + let body = build_request( + "claude-opus-5-5", + &ChatRequest { + system: "be brief", + messages: &messages, + tools: &tools, + }, + ); + assert_eq!(body["model"], "claude-opus-5-5"); + assert_eq!(body["max_tokens"], MAX_TOKENS); + assert_eq!(body["system"], "be brief"); + assert_eq!(body["cache_control"], json!({ "type": "ephemeral" })); + assert_eq!(body["tools"][0]["name"], "run_select_query"); + // The MCP schema is passed through as it is. + assert_eq!(body["tools"][0]["input_schema"], tools[0].input_schema); + assert_eq!( + body["messages"][0], + json!({ "role": "user", "content": "list providers" }) + ); + // Nothing that current models reject. + for absent in ["temperature", "top_p", "top_k", "thinking", "tool_choice"] { + assert!(body.get(absent).is_none(), "{absent} should not be sent"); + } + } + + #[test] + fn fallback_is_requested_only_for_models_that_take_it() { + let messages = vec![Message::User { text: "hi".into() }]; + let request = ChatRequest { + system: "", + messages: &messages, + tools: &[], + }; + assert_eq!( + build_request("claude-opus-5-5", &request)["fallbacks"], + "default" + ); + assert_eq!( + build_request("claude-sonnet-5-5", &request)["fallbacks"], + "default" + ); + assert!( + build_request("claude-haiku-5-5", &request) + .get("fallbacks") + .is_none() + ); + assert!( + build_request("some-other-model", &request) + .get("fallbacks") + .is_none() + ); + } + + #[test] + fn a_tool_use_reply_is_parsed_and_kept_whole() { + let reply = json!({ + "content": [ + { "type": "thinking", "thinking": "", "signature": "sig-1" }, + { "type": "text", "text": "Let me check." }, + { "type": "tool_use", "id": "toolu_1", "name": "run_select_query", "input": { "sql": "SELECT 1" } }, + { "type": "tool_use", "id": "toolu_2", "name": "list_providers", "input": {} } + ], + "stop_reason": "tool_use", + "usage": { "input_tokens": 12, "cache_read_input_tokens": 900, "cache_creation_input_tokens": 0, "output_tokens": 40 } + }); + let response = parse_response(&reply).unwrap(); + assert_eq!(response.text, "Let me check."); + assert_eq!(response.tool_calls.len(), 2); + assert_eq!(response.tool_calls[0].id, "toolu_1"); + assert_eq!(response.tool_calls[0].arguments["sql"], "SELECT 1"); + assert_eq!(response.stop, StopReason::ToolUse); + // Cached and uncached input are added together. + assert_eq!(response.usage.input_tokens, Some(912)); + assert_eq!(response.usage.output_tokens, Some(40)); + // What was read from the cache is in the input, and also told apart. + assert_eq!(response.usage.cached_input_tokens, Some(900)); + // The thinking block survives in what is kept for replay. + assert_eq!(response.raw.as_ref().unwrap()[0]["signature"], "sig-1"); + } + + #[test] + fn the_kept_reply_is_sent_back_untouched_followed_by_one_message_of_results() { + let raw = json!([ + { "type": "thinking", "thinking": "", "signature": "sig-1" }, + { "type": "tool_use", "id": "toolu_1", "name": "run_select_query", "input": { "sql": "SELECT 1" } }, + { "type": "tool_use", "id": "toolu_2", "name": "run_mutation_query", "input": { "sql": "DELETE" } } + ]); + let messages = vec![ + Message::User { text: "go".into() }, + Message::Assistant { + text: String::new(), + tool_calls: Vec::new(), + raw: Some(raw.clone()), + }, + Message::ToolResults { + results: vec![ + ToolOutcome { + call_id: "toolu_1".into(), + name: "run_select_query".into(), + content: "| one |".into(), + is_error: false, + }, + ToolOutcome { + call_id: "toolu_2".into(), + name: "run_mutation_query".into(), + content: "refused: user declined approval".into(), + is_error: true, + }, + ], + }, + ]; + let body = build_request( + "claude-opus-5-5", + &ChatRequest { + system: "", + messages: &messages, + tools: &[], + }, + ); + assert_eq!( + body["messages"][1], + json!({ "role": "assistant", "content": raw }) + ); + let results = &body["messages"][2]; + assert_eq!(results["role"], "user"); + assert_eq!(results["content"].as_array().unwrap().len(), 2); + assert_eq!( + results["content"][0], + json!({ "type": "tool_result", "tool_use_id": "toolu_1", "content": "| one |" }) + ); + assert_eq!(results["content"][1]["is_error"], true); + assert!(body.get("system").is_none()); + } + + #[test] + fn a_turn_the_host_wrote_itself_is_sent_as_plain_blocks() { + let messages = vec![Message::Assistant { + text: "[The operator stopped this turn.]".into(), + tool_calls: Vec::new(), + raw: None, + }]; + let body = build_request( + "m", + &ChatRequest { + system: "", + messages: &messages, + tools: &[], + }, + ); + assert_eq!( + body["messages"][0]["content"], + json!([{ "type": "text", "text": "[The operator stopped this turn.]" }]) + ); + } + + #[test] + fn a_refusal_is_reported_and_runs_no_tools() { + let reply = json!({ + "content": [{ "type": "tool_use", "id": "toolu_1", "name": "run_mutation_query", "input": {} }], + "stop_reason": "refusal", + "stop_details": { "type": "refusal", "category": "cyber", "explanation": "This request was declined." } + }); + let response = parse_response(&reply).unwrap(); + assert!( + matches!(&response.stop, StopReason::Refused(m) if m.contains("This request was declined.")) + ); + assert!(response.tool_calls.is_empty()); + } + + #[test] + fn stop_reasons_map_across() { + let with = |reason: &str| { + parse_response( + &json!({ "content": [{ "type": "text", "text": "x" }], "stop_reason": reason }), + ) + .unwrap() + .stop + }; + assert_eq!(with("end_turn"), StopReason::EndTurn); + assert_eq!(with("max_tokens"), StopReason::MaxTokens); + assert_eq!(with("pause_turn"), StopReason::Other("pause_turn".into())); + } + + #[test] + fn a_reply_without_content_is_a_protocol_error() { + assert!(matches!( + parse_response(&json!({ "stop_reason": "end_turn" })), + Err(InferenceError::Protocol(_)) + )); + } + + #[tokio::test] + async fn the_request_carries_the_key_the_version_and_the_fallback_beta() { + let (base, captured) = serve_once( + 200, + json!({ "content": [{ "type": "text", "text": "hello" }], "stop_reason": "end_turn", "usage": { "input_tokens": 5, "output_tokens": 2 } }), + ) + .await; + let backend = Anthropic::new( + reqwest::Client::new(), + base, + "claude-opus-5-5".into(), + "sk-test".into(), + ); + let messages = vec![Message::User { text: "hi".into() }]; + let response = backend + .complete(ChatRequest { + system: "sys", + messages: &messages, + tools: &[], + }) + .await + .unwrap(); + assert_eq!(response.text, "hello"); + + let request = captured.await.unwrap(); + assert_eq!(request.method, "POST"); + assert_eq!(request.path, "/v1/messages"); + assert_eq!(request.header("x-api-key"), Some("sk-test")); + assert_eq!(request.header("anthropic-version"), Some(API_VERSION)); + assert_eq!(request.header("anthropic-beta"), Some(FALLBACK_BETA)); + assert_eq!(request.body["fallbacks"], "default"); + } + + #[tokio::test] + async fn a_model_without_fallback_gets_no_beta_header() { + let (base, captured) = serve_once( + 200, + json!({ "content": [{ "type": "text", "text": "ok" }], "stop_reason": "end_turn" }), + ) + .await; + let backend = Anthropic::new( + reqwest::Client::new(), + base, + "claude-haiku-5-5".into(), + "sk-test".into(), + ); + let messages = vec![Message::User { text: "hi".into() }]; + backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap(); + let request = captured.await.unwrap(); + assert_eq!(request.header("anthropic-beta"), None); + assert!(request.body.get("fallbacks").is_none()); + } + + #[tokio::test] + async fn errors_are_classified_by_status() { + let cases = [ + (401, "authentication_error", "invalid x-api-key"), + (429, "rate_limit_error", "slow down"), + (529, "overloaded_error", "Overloaded"), + (400, "invalid_request_error", "prompt is too long"), + ]; + for (status, kind, message) in cases { + let (base, _captured) = serve_once( + status, + json!({ "type": "error", "error": { "type": kind, "message": message } }), + ) + .await; + let backend = Anthropic::new(reqwest::Client::new(), base, "m".into(), "k".into()); + let messages = vec![Message::User { text: "hi".into() }]; + let err = backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap_err(); + let matched = match status { + 401 => matches!(err, InferenceError::Auth(_)), + 429 => matches!(err, InferenceError::RateLimited(_)), + 529 => matches!(err, InferenceError::Unavailable(_)), + _ => matches!(err, InferenceError::InvalidRequest(_)), + }; + assert!(matched, "status {status} gave {err:?}"); + assert!(err.to_string().contains(message), "{err}"); + } + } +} diff --git a/src-tauri/src/agent/backends/gemini.rs b/src-tauri/src/agent/backends/gemini.rs new file mode 100644 index 0000000..d8ba45f --- /dev/null +++ b/src-tauri/src/agent/backends/gemini.rs @@ -0,0 +1,594 @@ +//! Gemini, through the `generateContent` REST method, with an API key. +//! +//! Wire format notes, from the Gemini API documentation as read in November +//! 2026: +//! +//! - `POST {base}/v1beta/models/{model}:generateContent`, key in the +//! `x-goog-api-key` header. +//! - Tools go in `tools[].functionDeclarations`. `parametersJsonSchema` +//! takes a standard JSON Schema, so the MCP tool schemas pass unchanged. +//! - A function call is a part of the model's reply. Newer models attach a +//! `thoughtSignature` to it, which must come back exactly where it was. +//! The whole reply is therefore kept and returned untouched. +//! - Results go back as `functionResponse` parts in one `user` turn, matched +//! to their calls by `id`. +//! - Sampling parameters such as temperature are not sent. Current models +//! ignore them and later ones are documented to reject them. + +use futures_util::FutureExt; +use futures_util::future::BoxFuture; +use serde_json::{Map, Value, json}; + +use super::post_json; +use crate::agent::backend::{ + ChatRequest, ChatResponse, InferenceBackend, InferenceError, Message, StopReason, ToolCall, + Usage, +}; + +pub const DEFAULT_BASE_URL: &str = "https://generativelanguage.googleapis.com"; +/// Available on the free tier, and the model the documentation points new +/// projects at. +pub const DEFAULT_MODEL: &str = "gemini-4-hydrogen"; + +/// Output limit. It includes the model's reasoning, so it is generous. +const MAX_OUTPUT_TOKENS: u32 = 32_768; +/// Marks a call id this client invented because the model sent none. Such an +/// id is for matching inside the host only and is not sent back. +const LOCAL_ID_PREFIX: &str = "local-call-"; + +pub struct Gemini { + http: reqwest::Client, + base_url: String, + model: String, + api_key: String, +} + +impl Gemini { + pub fn new(http: reqwest::Client, base_url: String, model: String, api_key: String) -> Self { + Self { + http, + base_url, + model, + api_key, + } + } + + fn url(&self) -> String { + // Accept a model written as "models/name", as the list API returns it. + let model = self.model.trim_start_matches("models/"); + format!("{}/v1beta/models/{model}:generateContent", self.base_url) + } +} + +impl InferenceBackend for Gemini { + fn complete<'a>( + &'a self, + request: ChatRequest<'a>, + ) -> BoxFuture<'a, Result> { + async move { + let body = build_request(&request); + let reply = post_json( + &self.http, + &self.url(), + &[("x-goog-api-key", &self.api_key)], + &body, + error_message, + ) + .await + .map_err(reclassify_key_error)?; + parse_response(&reply) + } + .boxed() + } +} + +fn error_message(body: &Value) -> Option { + let error = body.get("error")?; + let message = error.get("message")?.as_str()?; + let status = error.get("status").and_then(Value::as_str).unwrap_or(""); + Some(format!("{status} {message}").trim().to_string()) +} + +/// A bad key comes back as 400 INVALID_ARGUMENT, not as 401. +fn reclassify_key_error(err: InferenceError) -> InferenceError { + match err { + InferenceError::InvalidRequest(message) if message.contains("API key") => { + InferenceError::Auth(message) + } + other => other, + } +} + +pub fn build_request(request: &ChatRequest<'_>) -> Value { + let mut body = Map::new(); + if !request.system.is_empty() { + body.insert( + "systemInstruction".into(), + json!({ "parts": [{ "text": request.system }] }), + ); + } + body.insert( + "contents".into(), + Value::Array(request.messages.iter().map(content_of).collect()), + ); + if !request.tools.is_empty() { + let declarations: Vec = request + .tools + .iter() + .map(|tool| { + json!({ + "name": tool.name, + "description": tool.description, + "parametersJsonSchema": tool.input_schema, + }) + }) + .collect(); + body.insert( + "tools".into(), + json!([{ "functionDeclarations": declarations }]), + ); + } + body.insert( + "generationConfig".into(), + json!({ "maxOutputTokens": MAX_OUTPUT_TOKENS }), + ); + Value::Object(body) +} + +fn content_of(message: &Message) -> Value { + match message { + Message::User { text } => json!({ "role": "user", "parts": [{ "text": text }] }), + // The model's own reply goes back exactly as it arrived, signatures + // included. Rebuilding it would lose them. + Message::Assistant { raw: Some(raw), .. } => raw.clone(), + Message::Assistant { + text, tool_calls, .. + } => { + let mut parts = Vec::new(); + if !text.is_empty() { + parts.push(json!({ "text": text })); + } + for call in tool_calls { + let mut function_call = json!({ "name": call.name, "args": call.arguments }); + if !call.id.starts_with(LOCAL_ID_PREFIX) { + function_call["id"] = json!(call.id); + } + parts.push(json!({ "functionCall": function_call })); + } + if parts.is_empty() { + parts.push(json!({ "text": "" })); + } + json!({ "role": "model", "parts": parts }) + } + Message::ToolResults { results } => { + let parts: Vec = results + .iter() + .map(|result| { + // The response must be an object. An "error" key is how a + // failed call is reported. + let key = if result.is_error { "error" } else { "result" }; + let mut response = json!({ + "name": result.name, + "response": { key: result.content }, + }); + if !result.call_id.starts_with(LOCAL_ID_PREFIX) { + response["id"] = json!(result.call_id); + } + json!({ "functionResponse": response }) + }) + .collect(); + json!({ "role": "user", "parts": parts }) + } + } +} + +pub fn parse_response(reply: &Value) -> Result { + // The API counts the prompt, the reply and the model's thinking apart, + // and gives the total as their sum. Thinking is billed as output, so it + // is counted as output here. The prompt count already holds what was + // read from the cache. + let count = |name: &str| { + reply + .pointer(&format!("/usageMetadata/{name}")) + .and_then(Value::as_u64) + }; + let sum = |parts: [Option; 2]| { + parts + .iter() + .any(Option::is_some) + .then(|| parts.iter().flatten().sum()) + }; + let usage = Usage { + input_tokens: sum([count("promptTokenCount"), count("toolUsePromptTokenCount")]), + output_tokens: sum([count("candidatesTokenCount"), count("thoughtsTokenCount")]), + cached_input_tokens: count("cachedContentTokenCount"), + }; + + let Some(candidate) = reply.pointer("/candidates/0") else { + // No candidates means the prompt itself was blocked. + let reason = reply + .pointer("/promptFeedback/blockReason") + .and_then(Value::as_str) + .unwrap_or("no reason given"); + return Ok(ChatResponse { + text: String::new(), + tool_calls: Vec::new(), + raw: None, + stop: StopReason::Refused(format!("The request was blocked: {reason}")), + usage, + }); + }; + + let content = candidate.get("content"); + let parts = content + .and_then(|c| c.get("parts")) + .and_then(Value::as_array) + .cloned() + .unwrap_or_default(); + + let mut text = String::new(); + let mut tool_calls = Vec::new(); + for part in &parts { + // Parts flagged as thought are the model's reasoning, not its answer. + if part.get("thought").and_then(Value::as_bool) == Some(true) { + continue; + } + if let Some(piece) = part.get("text").and_then(Value::as_str) { + text.push_str(piece); + } + if let Some(call) = part.get("functionCall") { + let name = call + .get("name") + .and_then(Value::as_str) + .ok_or_else(|| InferenceError::Protocol("a function call had no name".into()))?; + let id = call + .get("id") + .and_then(Value::as_str) + .filter(|id| !id.is_empty()) + .map_or_else( + || format!("{LOCAL_ID_PREFIX}{}", tool_calls.len() + 1), + str::to_string, + ); + let arguments = call + .get("args") + .and_then(Value::as_object) + .cloned() + .unwrap_or_default(); + tool_calls.push(ToolCall { + id, + name: name.to_string(), + arguments, + }); + } + } + + let finish = candidate + .get("finishReason") + .and_then(Value::as_str) + .unwrap_or(""); + let stop = if !tool_calls.is_empty() { + StopReason::ToolUse + } else { + match finish { + "STOP" | "" => StopReason::EndTurn, + "MAX_TOKENS" => StopReason::MaxTokens, + "SAFETY" | "RECITATION" | "BLOCKLIST" | "PROHIBITED_CONTENT" | "SPII" => { + StopReason::Refused(format!("The model stopped: {finish}")) + } + other => StopReason::Other(other.to_string()), + } + }; + + // Only keep the reply for replay when it has something in it. An empty + // one cannot be sent back. + let raw = content.filter(|_| !parts.is_empty()).map(|c| { + let mut c = c.clone(); + if c.get("role").is_none() { + c["role"] = json!("model"); + } + c + }); + + Ok(ChatResponse { + text, + tool_calls, + raw, + stop, + usage, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::agent::backend::{ToolOutcome, ToolSpec}; + use crate::agent::backends::testing::serve_once; + + fn tools() -> Vec { + vec![ToolSpec { + name: "run_select_query".into(), + description: "Execute a SELECT.".into(), + input_schema: json!({ + "type": "object", + "additionalProperties": false, + "properties": { "sql": { "type": "string" } }, + "required": ["sql"] + }), + destructive: Some(false), + }] + } + + #[test] + fn the_request_carries_system_text_tools_and_no_sampling_parameters() { + let messages = vec![Message::User { + text: "list providers".into(), + }]; + let tools = tools(); + let body = build_request(&ChatRequest { + system: "be brief", + messages: &messages, + tools: &tools, + }); + assert_eq!(body["systemInstruction"]["parts"][0]["text"], "be brief"); + assert_eq!( + body["contents"][0], + json!({ "role": "user", "parts": [{ "text": "list providers" }] }) + ); + let declaration = &body["tools"][0]["functionDeclarations"][0]; + assert_eq!(declaration["name"], "run_select_query"); + // The MCP schema is passed through as it is. + assert_eq!(declaration["parametersJsonSchema"], tools[0].input_schema); + assert!(declaration.get("parameters").is_none()); + assert!(body["generationConfig"].get("temperature").is_none()); + assert_eq!( + body["generationConfig"]["maxOutputTokens"], + MAX_OUTPUT_TOKENS + ); + } + + #[test] + fn without_tools_the_tools_field_is_left_out() { + let messages = vec![Message::User { text: "hi".into() }]; + let body = build_request(&ChatRequest { + system: "", + messages: &messages, + tools: &[], + }); + assert!(body.get("tools").is_none()); + assert!(body.get("systemInstruction").is_none()); + } + + #[test] + fn a_function_call_reply_is_parsed_and_kept_whole() { + let reply = json!({ + "candidates": [{ + "content": { "role": "model", "parts": [ + { "thought": true, "text": "I should list providers." }, + { "text": "Looking that up." }, + { "functionCall": { "id": "fc-1", "name": "run_select_query", "args": { "sql": "SELECT 1" } }, + "thoughtSignature": "sig-abc" }, + { "functionCall": { "id": "fc-2", "name": "list_providers", "args": {} } } + ]}, + "finishReason": "STOP" + }], + "usageMetadata": { "promptTokenCount": 120, "cachedContentTokenCount": 100, "candidatesTokenCount": 30, "thoughtsTokenCount": 50, "totalTokenCount": 200 } + }); + let response = parse_response(&reply).unwrap(); + // Reasoning is not answer text. + assert_eq!(response.text, "Looking that up."); + assert_eq!(response.tool_calls.len(), 2); + assert_eq!(response.tool_calls[0].id, "fc-1"); + assert_eq!(response.tool_calls[0].arguments["sql"], "SELECT 1"); + assert_eq!(response.tool_calls[1].name, "list_providers"); + assert_eq!(response.stop, StopReason::ToolUse); + assert_eq!(response.usage.input_tokens, Some(120)); + // Thinking is counted apart from the reply and billed as output. + assert_eq!(response.usage.output_tokens, Some(80)); + assert_eq!(response.usage.cached_input_tokens, Some(100)); + // The signature survives in the kept reply. + assert_eq!( + response.raw.as_ref().unwrap()["parts"][2]["thoughtSignature"], + "sig-abc" + ); + } + + #[test] + fn the_kept_reply_is_sent_back_untouched_followed_by_the_results() { + let raw = json!({ "role": "model", "parts": [ + { "functionCall": { "id": "fc-1", "name": "run_select_query", "args": { "sql": "SELECT 1" } }, + "thoughtSignature": "sig-abc" } + ]}); + let messages = vec![ + Message::User { text: "go".into() }, + Message::Assistant { + text: String::new(), + tool_calls: vec![ToolCall { + id: "fc-1".into(), + name: "run_select_query".into(), + arguments: Map::new(), + }], + raw: Some(raw.clone()), + }, + Message::ToolResults { + results: vec![ + ToolOutcome { + call_id: "fc-1".into(), + name: "run_select_query".into(), + content: "| one |".into(), + is_error: false, + }, + ToolOutcome { + call_id: "fc-2".into(), + name: "run_mutation_query".into(), + content: "refused: user declined approval".into(), + is_error: true, + }, + ], + }, + ]; + let body = build_request(&ChatRequest { + system: "", + messages: &messages, + tools: &[], + }); + assert_eq!(body["contents"][1], raw); + // All results for one model turn share one user turn, matched by id. + let results = &body["contents"][2]; + assert_eq!(results["role"], "user"); + assert_eq!( + results["parts"][0]["functionResponse"], + json!({ "id": "fc-1", "name": "run_select_query", "response": { "result": "| one |" } }) + ); + assert_eq!( + results["parts"][1]["functionResponse"]["response"], + json!({ "error": "refused: user declined approval" }) + ); + } + + #[test] + fn a_call_without_an_id_gets_a_local_one_that_is_not_sent_back() { + let reply = json!({ "candidates": [{ "content": { "parts": [ + { "functionCall": { "name": "list_providers", "args": {} } } + ]}}]}); + let response = parse_response(&reply).unwrap(); + let id = response.tool_calls[0].id.clone(); + assert!(id.starts_with(LOCAL_ID_PREFIX)); + // A reply that arrived without a role still goes back as the model's. + assert_eq!(response.raw.as_ref().unwrap()["role"], "model"); + + let messages = vec![Message::ToolResults { + results: vec![ToolOutcome { + call_id: id, + name: "list_providers".into(), + content: "ok".into(), + is_error: false, + }], + }]; + let body = build_request(&ChatRequest { + system: "", + messages: &messages, + tools: &[], + }); + assert!( + body["contents"][0]["parts"][0]["functionResponse"] + .get("id") + .is_none() + ); + } + + #[test] + fn finish_reasons_map_to_stop_reasons() { + let with = |finish: &str| { + parse_response(&json!({ "candidates": [{ + "content": { "role": "model", "parts": [{ "text": "x" }] }, + "finishReason": finish + }]})) + .unwrap() + .stop + }; + assert_eq!(with("STOP"), StopReason::EndTurn); + assert_eq!(with("MAX_TOKENS"), StopReason::MaxTokens); + assert!(matches!(with("SAFETY"), StopReason::Refused(_))); + assert_eq!( + with("MALFORMED_FUNCTION_CALL"), + StopReason::Other("MALFORMED_FUNCTION_CALL".into()) + ); + } + + #[test] + fn a_blocked_prompt_is_a_refusal_not_a_crash() { + let response = + parse_response(&json!({ "promptFeedback": { "blockReason": "SAFETY" } })).unwrap(); + assert!(matches!(&response.stop, StopReason::Refused(m) if m.contains("SAFETY"))); + assert!(response.text.is_empty()); + assert_eq!(response.raw, None); + } + + #[test] + fn an_empty_reply_is_not_kept_for_replay() { + let response = parse_response(&json!({ "candidates": [{ + "content": { "role": "model", "parts": [] }, "finishReason": "MAX_TOKENS" + }]})) + .unwrap(); + assert_eq!(response.raw, None); + assert_eq!(response.stop, StopReason::MaxTokens); + } + + #[tokio::test] + async fn the_request_goes_to_the_right_place_with_the_key_in_a_header() { + let (base, captured) = serve_once( + 200, + json!({ "candidates": [{ "content": { "role": "model", "parts": [{ "text": "hello" }] }, "finishReason": "STOP" }] }), + ) + .await; + let backend = Gemini::new( + reqwest::Client::new(), + base, + "models/gemini-test".into(), + "key-123".into(), + ); + let messages = vec![Message::User { text: "hi".into() }]; + let response = backend + .complete(ChatRequest { + system: "sys", + messages: &messages, + tools: &[], + }) + .await + .unwrap(); + assert_eq!(response.text, "hello"); + + let request = captured.await.unwrap(); + assert_eq!(request.method, "POST"); + assert_eq!(request.path, "/v1beta/models/gemini-test:generateContent"); + assert_eq!(request.header("x-goog-api-key"), Some("key-123")); + // The key is never in the URL. + assert!(!request.path.contains("key-123")); + assert_eq!(request.body["contents"][0]["parts"][0]["text"], "hi"); + } + + #[tokio::test] + async fn a_rejected_key_is_reported_as_an_auth_problem() { + let (base, _captured) = serve_once( + 400, + json!({ "error": { "code": 400, "message": "API key not valid. Please pass a valid API key.", "status": "INVALID_ARGUMENT" } }), + ) + .await; + let backend = Gemini::new(reqwest::Client::new(), base, "m".into(), "bad".into()); + let messages = vec![Message::User { text: "hi".into() }]; + let err = backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap_err(); + assert!( + matches!(&err, InferenceError::Auth(m) if m.contains("API key not valid")), + "{err:?}" + ); + // The error text does not repeat the key. + assert!(!err.to_string().contains("bad\"")); + } + + #[tokio::test] + async fn rate_limiting_is_reported_as_such() { + let (base, _captured) = serve_once( + 429, + json!({ "error": { "code": 429, "message": "Quota exceeded", "status": "RESOURCE_EXHAUSTED" } }), + ) + .await; + let backend = Gemini::new(reqwest::Client::new(), base, "m".into(), "k".into()); + let messages = vec![Message::User { text: "hi".into() }]; + let err = backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap_err(); + assert!(matches!(&err, InferenceError::RateLimited(m) if m.contains("RESOURCE_EXHAUSTED"))); + } +} diff --git a/src-tauri/src/agent/backends/mod.rs b/src-tauri/src/agent/backends/mod.rs new file mode 100644 index 0000000..265e087 --- /dev/null +++ b/src-tauri/src/agent/backends/mod.rs @@ -0,0 +1,303 @@ +//! Inference backends that authenticate with an API key. +//! +//! Each one translates the shared conversation into its provider's wire +//! format and back. None of them holds state between calls, and none of them +//! ever sees engine credentials: a conversation contains only what the +//! operator typed and what tools returned. + +pub mod anthropic; +pub mod gemini; +pub mod openai; + +use std::sync::Arc; +use std::time::Duration; + +use serde_json::Value; + +use super::backend::{ + BackendKind, InferenceBackend, InferenceError, classify_http_error, classify_transport_error, +}; +use crate::config::InferenceSettings; +use crate::util::truncate; + +/// How long one model call may take. Models that reason before answering +/// can take minutes. +const REQUEST_TIMEOUT: Duration = Duration::from_secs(300); + +/// The model used when the operator has not chosen one. +pub fn default_model(kind: BackendKind) -> &'static str { + match kind { + BackendKind::Gemini => gemini::DEFAULT_MODEL, + BackendKind::Anthropic => anthropic::DEFAULT_MODEL, + // There is no sensible default for an arbitrary compatible server. + BackendKind::OpenaiCompatible => "", + // Empty leaves the choice to the agent. + BackendKind::GithubCopilot => "", + } +} + +/// The address used when the operator has not set one. +pub fn default_base_url(kind: BackendKind) -> &'static str { + match kind { + BackendKind::Gemini => gemini::DEFAULT_BASE_URL, + BackendKind::Anthropic => anthropic::DEFAULT_BASE_URL, + BackendKind::OpenaiCompatible => openai::DEFAULT_BASE_URL, + // A delegated agent has no address of ours. + BackendKind::GithubCopilot => "", + } +} + +/// Builds the backend the settings describe. +pub fn build( + settings: &InferenceSettings, + api_key: Option, +) -> Result, InferenceError> { + if settings.kind.is_delegated() { + // A delegated agent runs its own loop. It has no request to build. + return Err(InferenceError::InvalidRequest( + "This backend is an agent, not a model API.".to_string(), + )); + } + let model = if settings.model.trim().is_empty() { + default_model(settings.kind).to_string() + } else { + settings.model.trim().to_string() + }; + if model.is_empty() { + return Err(InferenceError::InvalidRequest( + "No model is set. Choose one in Settings.".to_string(), + )); + } + let base_url = settings + .base_url + .as_deref() + .map(str::trim) + .filter(|url| !url.is_empty()) + .unwrap_or_else(|| default_base_url(settings.kind)) + .trim_end_matches('/') + .to_string(); + let api_key = api_key.filter(|key| !key.trim().is_empty()); + if api_key.is_none() && !settings.kind.key_optional() { + return Err(InferenceError::Auth( + "No API key is stored for this backend".to_string(), + )); + } + let http = http_client()?; + Ok(match settings.kind { + BackendKind::Gemini => Arc::new(gemini::Gemini::new( + http, + base_url, + model, + api_key.unwrap_or_default(), + )), + BackendKind::Anthropic => Arc::new(anthropic::Anthropic::new( + http, + base_url, + model, + api_key.unwrap_or_default(), + )), + BackendKind::OpenaiCompatible => Arc::new(openai::OpenAiCompatible::new( + http, base_url, model, api_key, + )), + BackendKind::GithubCopilot => { + return Err(InferenceError::InvalidRequest( + "This backend is an agent, not a model API.".to_string(), + )); + } + }) +} + +fn http_client() -> Result { + reqwest::Client::builder() + .timeout(REQUEST_TIMEOUT) + .connect_timeout(Duration::from_secs(15)) + .user_agent(concat!("stackql-workbench/", env!("CARGO_PKG_VERSION"))) + .build() + .map_err(|err| InferenceError::Network(err.to_string())) +} + +/// Posts JSON and returns the parsed reply. `error_message` digs the +/// provider's message out of an error body. +async fn post_json( + http: &reqwest::Client, + url: &str, + headers: &[(&str, &str)], + body: &Value, + error_message: fn(&Value) -> Option, +) -> Result { + let mut request = http.post(url).json(body); + for (name, value) in headers { + request = request.header(*name, *value); + } + let response = request + .send() + .await + .map_err(|err| classify_transport_error(&err))?; + let status = response.status(); + let text = response + .text() + .await + .map_err(|err| classify_transport_error(&err))?; + + if !status.is_success() { + let message = serde_json::from_str::(&text) + .ok() + .and_then(|json| error_message(&json)) + .unwrap_or_else(|| truncate(text.trim(), 300)); + return Err(classify_http_error( + status.as_u16(), + format!("HTTP {}: {message}", status.as_u16()), + )); + } + serde_json::from_str(&text) + .map_err(|err| InferenceError::Protocol(format!("the reply was not JSON: {err}"))) +} + +#[cfg(test)] +pub(crate) mod testing { + //! A one-shot HTTP server for backend tests. It records the request it + //! receives and answers with a canned reply, so a test can check exactly + //! what a backend puts on the wire without calling a real provider. + + use tokio::io::{AsyncReadExt, AsyncWriteExt}; + use tokio::net::TcpListener; + use tokio::sync::oneshot; + + pub struct Captured { + pub method: String, + pub path: String, + /// Header names are lower-cased. + pub headers: Vec<(String, String)>, + pub body: serde_json::Value, + } + + impl Captured { + pub fn header(&self, name: &str) -> Option<&str> { + self.headers + .iter() + .find(|(k, _)| k == name) + .map(|(_, v)| v.as_str()) + } + } + + /// Starts a server that answers one request. Returns its base URL and a + /// receiver for what it was sent. + pub async fn serve_once( + status: u16, + reply: serde_json::Value, + ) -> (String, oneshot::Receiver) { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let (tx, rx) = oneshot::channel(); + tokio::spawn(async move { + let (mut socket, _) = listener.accept().await.unwrap(); + let mut data = Vec::new(); + let mut chunk = [0u8; 8192]; + let (head_end, length) = loop { + let n = socket.read(&mut chunk).await.unwrap(); + assert!(n > 0, "the client closed before sending a full request"); + data.extend_from_slice(&chunk[..n]); + if let Some(end) = data.windows(4).position(|w| w == b"\r\n\r\n") { + let head = String::from_utf8_lossy(&data[..end]).to_ascii_lowercase(); + let length = head + .lines() + .find_map(|l| l.strip_prefix("content-length:")) + .map_or(0, |v| v.trim().parse::().unwrap()); + break (end + 4, length); + } + }; + while data.len() < head_end + length { + let n = socket.read(&mut chunk).await.unwrap(); + assert!(n > 0, "the client closed before sending the whole body"); + data.extend_from_slice(&chunk[..n]); + } + + let head = String::from_utf8_lossy(&data[..head_end]).into_owned(); + let mut lines = head.lines(); + let mut request_line = lines.next().unwrap_or_default().split_whitespace(); + let method = request_line.next().unwrap_or_default().to_string(); + let path = request_line.next().unwrap_or_default().to_string(); + let headers = lines + .filter_map(|l| l.split_once(':')) + .map(|(k, v)| (k.trim().to_ascii_lowercase(), v.trim().to_string())) + .collect(); + let body = serde_json::from_slice(&data[head_end..head_end + length]) + .unwrap_or(serde_json::Value::Null); + + let payload = reply.to_string(); + let response = format!( + "HTTP/1.1 {status} X\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{payload}", + payload.len() + ); + socket.write_all(response.as_bytes()).await.unwrap(); + let _ = socket.shutdown().await; + let _ = tx.send(Captured { + method, + path, + headers, + body, + }); + }); + (format!("http://{address}"), rx) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn settings(kind: BackendKind, model: &str, base_url: Option<&str>) -> InferenceSettings { + InferenceSettings { + kind, + model: model.to_string(), + base_url: base_url.map(str::to_string), + program: None, + subagents: true, + } + } + + #[test] + fn a_backend_that_needs_a_key_is_not_built_without_one() { + for kind in [BackendKind::Gemini, BackendKind::Anthropic] { + let err = build(&settings(kind, "", None), None).err().unwrap(); + assert!(matches!(err, InferenceError::Auth(_)), "{kind:?}"); + let err = build(&settings(kind, "", None), Some(" ".into())) + .err() + .unwrap(); + assert!(matches!(err, InferenceError::Auth(_)), "{kind:?}"); + } + } + + #[test] + fn a_compatible_server_needs_a_model_but_not_a_key() { + let err = build(&settings(BackendKind::OpenaiCompatible, "", None), None) + .err() + .unwrap(); + assert!(matches!(err, InferenceError::InvalidRequest(_))); + assert!( + build( + &settings( + BackendKind::OpenaiCompatible, + "local-model", + Some("http://127.0.0.1:11434/v1/") + ), + None + ) + .is_ok() + ); + } + + #[test] + fn defaults_exist_where_they_make_sense() { + assert!(!default_model(BackendKind::Gemini).is_empty()); + assert!(!default_model(BackendKind::Anthropic).is_empty()); + assert!(default_model(BackendKind::OpenaiCompatible).is_empty()); + for kind in [ + BackendKind::Gemini, + BackendKind::Anthropic, + BackendKind::OpenaiCompatible, + ] { + assert!(default_base_url(kind).starts_with("https://")); + } + } +} diff --git a/src-tauri/src/agent/backends/openai.rs b/src-tauri/src/agent/backends/openai.rs new file mode 100644 index 0000000..fa14254 --- /dev/null +++ b/src-tauri/src/agent/backends/openai.rs @@ -0,0 +1,552 @@ +//! OpenAI's Chat Completions API, and any server that implements it. +//! +//! This is the format local inference servers speak, which is why it is the +//! one used here: a configurable base URL covers OpenAI and local models +//! alike. Wire format: +//! +//! - `POST {base}/chat/completions`, where the base normally ends in `/v1`. +//! The key goes in `Authorization: Bearer`. A local server may need none. +//! - Tools are `{ type: "function", function: { name, description, parameters } }`. +//! - A tool call's arguments arrive as a JSON string, not an object. +//! - Each result goes back as its own `tool` message, matched by +//! `tool_call_id`. +//! +//! Limitation: OpenAI's documentation says some of its newest models take +//! tool calls only through its Responses API, which this does not implement. + +use futures_util::FutureExt; +use futures_util::future::BoxFuture; +use serde_json::{Map, Value, json}; + +use super::post_json; +use crate::agent::backend::{ + ChatRequest, ChatResponse, InferenceBackend, InferenceError, Message, StopReason, ToolCall, + Usage, +}; + +pub const DEFAULT_BASE_URL: &str = "https://api.openai.com/v1"; + +/// The key under which arguments that were not valid JSON are passed on. The +/// engine rejects the unknown argument, and that error tells the model to +/// try again, which is better than guessing what it meant. +const UNPARSED_ARGUMENTS: &str = "unparsed_arguments"; + +pub struct OpenAiCompatible { + http: reqwest::Client, + base_url: String, + model: String, + api_key: Option, +} + +impl OpenAiCompatible { + pub fn new( + http: reqwest::Client, + base_url: String, + model: String, + api_key: Option, + ) -> Self { + Self { + http, + base_url, + model, + api_key, + } + } +} + +impl InferenceBackend for OpenAiCompatible { + fn complete<'a>( + &'a self, + request: ChatRequest<'a>, + ) -> BoxFuture<'a, Result> { + async move { + let body = build_request(&self.model, &request); + let bearer = self.api_key.as_ref().map(|key| format!("Bearer {key}")); + let headers: Vec<(&str, &str)> = bearer + .as_deref() + .map(|value| ("authorization", value)) + .into_iter() + .collect(); + let reply = post_json( + &self.http, + &format!("{}/chat/completions", self.base_url), + &headers, + &body, + error_message, + ) + .await?; + parse_response(&reply) + } + .boxed() + } +} + +fn error_message(body: &Value) -> Option { + let error = body.get("error")?; + // Some compatible servers send the error as a bare string. + if let Some(text) = error.as_str() { + return Some(text.to_string()); + } + error.get("message")?.as_str().map(str::to_string) +} + +pub fn build_request(model: &str, request: &ChatRequest<'_>) -> Value { + let mut messages = Vec::new(); + if !request.system.is_empty() { + // "system" is the role every compatible server understands. + messages.push(json!({ "role": "system", "content": request.system })); + } + for message in request.messages { + push_message(&mut messages, message); + } + + let mut body = Map::new(); + body.insert("model".into(), json!(model)); + body.insert("messages".into(), Value::Array(messages)); + if !request.tools.is_empty() { + let tools: Vec = request + .tools + .iter() + .map(|tool| { + json!({ + "type": "function", + "function": { + "name": tool.name, + "description": tool.description, + "parameters": tool.input_schema, + } + }) + }) + .collect(); + body.insert("tools".into(), Value::Array(tools)); + } + Value::Object(body) +} + +fn push_message(out: &mut Vec, message: &Message) { + match message { + Message::User { text } => out.push(json!({ "role": "user", "content": text })), + Message::Assistant { raw: Some(raw), .. } => out.push(raw.clone()), + Message::Assistant { + text, tool_calls, .. + } => { + let mut assistant = json!({ "role": "assistant", "content": text }); + if !tool_calls.is_empty() { + let calls: Vec = tool_calls + .iter() + .map(|call| { + json!({ + "id": call.id, + "type": "function", + "function": { + "name": call.name, + "arguments": Value::Object(call.arguments.clone()).to_string(), + } + }) + }) + .collect(); + assistant["tool_calls"] = Value::Array(calls); + } + out.push(assistant); + } + // One message per result. There is no flag for a failed call, so + // the content says so. + Message::ToolResults { results } => { + for result in results { + let content = if result.is_error { + format!("Error: {}", result.content) + } else { + result.content.clone() + }; + out.push(json!({ + "role": "tool", + "tool_call_id": result.call_id, + "content": content, + })); + } + } + } +} + +pub fn parse_response(reply: &Value) -> Result { + let choice = reply + .pointer("/choices/0") + .ok_or_else(|| InferenceError::Protocol("the reply had no choices".into()))?; + let message = choice + .get("message") + .ok_or_else(|| InferenceError::Protocol("the reply had no message".into()))?; + + let text = message + .get("content") + .and_then(Value::as_str) + .unwrap_or_default() + .to_string(); + + let mut tool_calls = Vec::new(); + for (index, call) in message + .get("tool_calls") + .and_then(Value::as_array) + .into_iter() + .flatten() + .enumerate() + { + let name = call + .pointer("/function/name") + .and_then(Value::as_str) + .ok_or_else(|| InferenceError::Protocol("a tool call had no name".into()))?; + let id = call + .get("id") + .and_then(Value::as_str) + .filter(|id| !id.is_empty()) + .map_or_else(|| format!("call_{}", index + 1), str::to_string); + tool_calls.push(ToolCall { + id, + name: name.to_string(), + arguments: parse_arguments(call.pointer("/function/arguments")), + }); + } + + let refusal = message + .get("refusal") + .and_then(Value::as_str) + .filter(|r| !r.is_empty()); + let stop = if let Some(refusal) = refusal { + tool_calls.clear(); + StopReason::Refused(refusal.to_string()) + } else if !tool_calls.is_empty() { + StopReason::ToolUse + } else { + match choice.get("finish_reason").and_then(Value::as_str) { + Some("stop") | None => StopReason::EndTurn, + Some("length") => StopReason::MaxTokens, + Some("content_filter") => { + StopReason::Refused("The reply was withheld by a content filter.".to_string()) + } + Some(other) => StopReason::Other(other.to_string()), + } + }; + + // `prompt_tokens` is the whole input and `completion_tokens` the whole + // output, reasoning included. A server that caches says how much of the + // input it read from its cache. A local server usually says none of it. + let usage = Usage { + input_tokens: reply + .pointer("/usage/prompt_tokens") + .and_then(Value::as_u64), + output_tokens: reply + .pointer("/usage/completion_tokens") + .and_then(Value::as_u64), + cached_input_tokens: reply + .pointer("/usage/prompt_tokens_details/cached_tokens") + .and_then(Value::as_u64), + }; + + // The message goes back as it came, so that fields a particular server + // adds to it are not lost. Calls that had no id get the one made up + // here, so that their results can be matched. + let mut raw = message.clone(); + if raw.get("role").is_none() { + raw["role"] = json!("assistant"); + } + if let Some(calls) = raw.get_mut("tool_calls").and_then(Value::as_array_mut) { + for (call, parsed) in calls.iter_mut().zip(&tool_calls) { + call["id"] = json!(parsed.id); + } + } + + Ok(ChatResponse { + text, + tool_calls, + raw: Some(raw), + stop, + usage, + }) +} + +/// Arguments arrive as a JSON string. Some servers send an object instead. +fn parse_arguments(value: Option<&Value>) -> Map { + match value { + Some(Value::Object(object)) => object.clone(), + Some(Value::String(text)) if text.trim().is_empty() => Map::new(), + Some(Value::String(text)) => match serde_json::from_str::(text) { + Ok(Value::Object(object)) => object, + _ => { + let mut wrapped = Map::new(); + wrapped.insert(UNPARSED_ARGUMENTS.to_string(), json!(text)); + wrapped + } + }, + _ => Map::new(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::agent::backend::{ToolOutcome, ToolSpec}; + use crate::agent::backends::testing::serve_once; + + fn tools() -> Vec { + vec![ToolSpec { + name: "run_select_query".into(), + description: "Execute a SELECT.".into(), + input_schema: json!({ "type": "object", "properties": { "sql": { "type": "string" } }, "required": ["sql"] }), + destructive: Some(false), + }] + } + + #[test] + fn the_request_has_the_expected_shape() { + let messages = vec![Message::User { + text: "list providers".into(), + }]; + let tools = tools(); + let body = build_request( + "local-model", + &ChatRequest { + system: "be brief", + messages: &messages, + tools: &tools, + }, + ); + assert_eq!(body["model"], "local-model"); + assert_eq!( + body["messages"][0], + json!({ "role": "system", "content": "be brief" }) + ); + assert_eq!( + body["messages"][1], + json!({ "role": "user", "content": "list providers" }) + ); + assert_eq!(body["tools"][0]["type"], "function"); + assert_eq!(body["tools"][0]["function"]["name"], "run_select_query"); + assert_eq!( + body["tools"][0]["function"]["parameters"], + tools[0].input_schema + ); + assert!(body.get("temperature").is_none()); + assert!(body.get("max_tokens").is_none()); + } + + #[test] + fn tool_calls_are_parsed_from_string_arguments() { + let reply = json!({ + "choices": [{ + "message": { + "role": "assistant", + "content": null, + "tool_calls": [ + { "id": "call_a", "type": "function", "function": { "name": "run_select_query", "arguments": "{\"sql\":\"SELECT 1\"}" } }, + { "id": "call_b", "type": "function", "function": { "name": "list_providers", "arguments": "" } } + ] + }, + "finish_reason": "tool_calls" + }], + "usage": { "prompt_tokens": 100, "completion_tokens": 20, "prompt_tokens_details": { "cached_tokens": 64 } } + }); + let response = parse_response(&reply).unwrap(); + assert_eq!(response.text, ""); + assert_eq!(response.tool_calls[0].id, "call_a"); + assert_eq!(response.tool_calls[0].arguments["sql"], "SELECT 1"); + assert!(response.tool_calls[1].arguments.is_empty()); + assert_eq!(response.stop, StopReason::ToolUse); + assert_eq!(response.usage.input_tokens, Some(100)); + assert_eq!(response.usage.output_tokens, Some(20)); + assert_eq!(response.usage.cached_input_tokens, Some(64)); + } + + #[test] + fn arguments_that_are_not_json_are_passed_on_for_the_engine_to_reject() { + let arguments = parse_arguments(Some(&json!("{not json"))); + assert_eq!(arguments[UNPARSED_ARGUMENTS], "{not json"); + // An object, which some servers send, is taken as it is. + assert_eq!(parse_arguments(Some(&json!({ "sql": "x" })))["sql"], "x"); + assert!(parse_arguments(None).is_empty()); + } + + #[test] + fn the_assistant_turn_and_one_message_per_result_go_back() { + let reply = json!({ "choices": [{ "message": { + "role": "assistant", "content": null, + "tool_calls": [{ "id": "call_a", "type": "function", "function": { "name": "run_select_query", "arguments": "{}" } }] + }}]}); + let response = parse_response(&reply).unwrap(); + let messages = vec![ + Message::User { text: "go".into() }, + response.into_message(), + Message::ToolResults { + results: vec![ + ToolOutcome { + call_id: "call_a".into(), + name: "run_select_query".into(), + content: "| one |".into(), + is_error: false, + }, + ToolOutcome { + call_id: "call_b".into(), + name: "run_mutation_query".into(), + content: "refused".into(), + is_error: true, + }, + ], + }, + ]; + let body = build_request( + "m", + &ChatRequest { + system: "", + messages: &messages, + tools: &[], + }, + ); + let sent = body["messages"].as_array().unwrap(); + assert_eq!(sent.len(), 4); + assert_eq!(sent[1]["tool_calls"][0]["id"], "call_a"); + assert_eq!( + sent[2], + json!({ "role": "tool", "tool_call_id": "call_a", "content": "| one |" }) + ); + assert_eq!(sent[3]["content"], "Error: refused"); + } + + #[test] + fn a_call_without_an_id_gets_one_that_matches_its_result() { + let reply = json!({ "choices": [{ "message": { + "content": "", "tool_calls": [{ "function": { "name": "list_providers", "arguments": "{}" } }] + }}]}); + let response = parse_response(&reply).unwrap(); + assert_eq!(response.tool_calls[0].id, "call_1"); + let raw = response.raw.unwrap(); + assert_eq!(raw["tool_calls"][0]["id"], "call_1"); + assert_eq!(raw["role"], "assistant"); + } + + #[test] + fn a_turn_the_host_wrote_itself_is_sent_with_string_arguments() { + let mut arguments = Map::new(); + arguments.insert("sql".into(), json!("SELECT 1")); + let messages = vec![Message::Assistant { + text: "running".into(), + tool_calls: vec![ToolCall { + id: "call_x".into(), + name: "run_select_query".into(), + arguments, + }], + raw: None, + }]; + let body = build_request( + "m", + &ChatRequest { + system: "", + messages: &messages, + tools: &[], + }, + ); + assert_eq!( + body["messages"][0]["tool_calls"][0]["function"]["arguments"], + "{\"sql\":\"SELECT 1\"}" + ); + } + + #[test] + fn finish_reasons_and_refusals_map_across() { + let with = |finish: &str| { + parse_response( + &json!({ "choices": [{ "message": { "content": "x" }, "finish_reason": finish }] }), + ) + .unwrap() + .stop + }; + assert_eq!(with("stop"), StopReason::EndTurn); + assert_eq!(with("length"), StopReason::MaxTokens); + assert!(matches!(with("content_filter"), StopReason::Refused(_))); + + let refused = parse_response(&json!({ "choices": [{ "message": { + "content": null, "refusal": "I can't help with that.", + "tool_calls": [{ "id": "c", "function": { "name": "run_mutation_query", "arguments": "{}" } }] + }}]})) + .unwrap(); + assert_eq!( + refused.stop, + StopReason::Refused("I can't help with that.".into()) + ); + assert!(refused.tool_calls.is_empty()); + } + + #[test] + fn a_reply_without_choices_is_a_protocol_error() { + assert!(matches!( + parse_response(&json!({ "object": "chat.completion" })), + Err(InferenceError::Protocol(_)) + )); + } + + #[tokio::test] + async fn the_request_goes_to_chat_completions_with_a_bearer_key() { + let (base, captured) = serve_once( + 200, + json!({ "choices": [{ "message": { "role": "assistant", "content": "hello" }, "finish_reason": "stop" }] }), + ) + .await; + let backend = OpenAiCompatible::new( + reqwest::Client::new(), + format!("{base}/v1"), + "m".into(), + Some("sk-test".into()), + ); + let messages = vec![Message::User { text: "hi".into() }]; + let response = backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap(); + assert_eq!(response.text, "hello"); + let request = captured.await.unwrap(); + assert_eq!(request.path, "/v1/chat/completions"); + assert_eq!(request.header("authorization"), Some("Bearer sk-test")); + } + + #[tokio::test] + async fn a_local_server_gets_no_authorization_header() { + let (base, captured) = serve_once( + 200, + json!({ "choices": [{ "message": { "content": "ok" }, "finish_reason": "stop" }] }), + ) + .await; + let backend = OpenAiCompatible::new(reqwest::Client::new(), base, "m".into(), None); + let messages = vec![Message::User { text: "hi".into() }]; + backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap(); + assert_eq!(captured.await.unwrap().header("authorization"), None); + } + + #[tokio::test] + async fn errors_carry_the_server_message_in_either_shape() { + for body in [ + json!({ "error": { "message": "Incorrect API key provided", "type": "invalid_request_error" } }), + json!({ "error": "Incorrect API key provided" }), + ] { + let (base, _captured) = serve_once(401, body).await; + let backend = OpenAiCompatible::new(reqwest::Client::new(), base, "m".into(), None); + let messages = vec![Message::User { text: "hi".into() }]; + let err = backend + .complete(ChatRequest { + system: "", + messages: &messages, + tools: &[], + }) + .await + .unwrap_err(); + assert!(matches!(&err, InferenceError::Auth(m) if m.contains("Incorrect API key"))); + } + } +} diff --git a/src-tauri/src/agent/copilot.rs b/src-tauri/src/agent/copilot.rs new file mode 100644 index 0000000..d7a06d6 --- /dev/null +++ b/src-tauri/src/agent/copilot.rs @@ -0,0 +1,313 @@ +//! How the GitHub Copilot CLI is started as a delegated agent. +//! +//! The CLI is the operator's own install, with the operator's own sign-in. +//! This module never touches that sign-in. It only decides the command +//! line, so that the agent works against this app's engine and nothing +//! else. Every choice here was tested. See `docs/spike-acp.md`. + +use std::ffi::{OsStr, OsString}; +use std::path::{Path, PathBuf}; + +use serde_json::{Value, json}; + +use super::delegate::Profile; +use crate::connection::McpServerCommand; + +/// The name the engine's MCP server is given in the CLI's configuration. +/// An entry of the same name in the operator's own configuration is +/// replaced by this one for the session, so the two never run side by side. +pub const SERVER_NAME: &str = "stackql"; + +pub const PROFILE: Profile = Profile { + name: "GitHub Copilot", + sign_in_hint: "Run `copilot login` in a terminal, then send the message again.", + tool_prefix: "stackql-", + vendor_key: "github.com/copilot", + // Without these the CLI gives a subagent's calls an id and no name. + session_events: &["subagent.started"], + // The CLI has three kinds of subagent. Under the tool list this app + // gives it, the general-purpose kind has the engine's tools and runs on + // the model the operator chose, the task kind has them and runs on a + // model the CLI picks, and the explore kind has none of them. A + // subagent started in the background needs tools to be read back that + // the agent does not have here. All of it was tested. + subagent_hint: "- With the task tool here, set agent_type to general-purpose and mode to sync, \ +and start the subagents in the same step so that they run together.\n\ +- Do not use the explore agent type, which does not have the stackql tools, or background mode.", +}; + +/// The CLI's tool for starting a subagent. A subagent gets the same tools +/// as the agent that starts it: the engine's, and this one. +pub const SUBAGENT_TOOL: &str = "task"; + +/// File names the CLI may have on this platform, best first. +fn program_names() -> &'static [&'static str] { + if cfg!(windows) { + // The npm install is a .cmd shim. Other installs are an .exe. + &["copilot.exe", "copilot.cmd"] + } else { + &["copilot"] + } +} + +/// Whether there is a program at the path. This does not follow links, +/// because a Windows app execution alias is a link that cannot be followed +/// and can still be run. +pub fn program_exists(path: &Path) -> bool { + std::fs::symlink_metadata(path).is_ok_and(|meta| !meta.is_dir()) +} + +/// Finds the CLI. A location the operator set is used or reported as wrong. +/// Otherwise `PATH` is searched. +pub fn find_program( + explicit: Option<&Path>, + path_var: Option<&OsStr>, + exists: impl Fn(&Path) -> bool, +) -> Result { + if let Some(path) = explicit { + return if exists(path) { + Ok(path.to_path_buf()) + } else { + Err(format!( + "The Copilot CLI location in Settings does not point to a file: {}. Correct it, or clear it to search PATH.", + path.display() + )) + }; + } + if let Some(path_var) = path_var { + for dir in std::env::split_paths(path_var) { + if dir.as_os_str().is_empty() { + continue; + } + for name in program_names() { + let candidate = dir.join(name); + if exists(&candidate) { + return Ok(candidate); + } + } + } + } + Err( + "The GitHub Copilot CLI was not found on PATH. Install it and run `copilot login`, or set its location in Settings." + .to_string(), + ) +} + +/// The names the CLI gives the engine's tools: the server name, a hyphen, +/// the tool name. +pub fn tool_ids(tools: &[String]) -> Vec { + tools + .iter() + .map(|tool| format!("{SERVER_NAME}-{tool}")) + .collect() +} + +/// The MCP configuration file that names the engine's MCP server. +pub fn mcp_config(server: &McpServerCommand) -> Result { + let text = |value: &OsStr| { + value.to_str().map(str::to_string).ok_or_else(|| { + format!( + "A path the engine is started with is not valid Unicode: {}", + value.to_string_lossy() + ) + }) + }; + let args = server + .args + .iter() + .map(|arg| text(arg)) + .collect::, _>>()?; + Ok(json!({ + "mcpServers": { + SERVER_NAME: { + "type": "local", + "command": text(server.program.as_os_str())?, + "args": args, + "cwd": text(server.cwd.as_os_str())?, + "tools": ["*"] + } + } + })) +} + +/// The arguments for `copilot`, given the configuration file and the tools +/// the model may use. With `subagents` the model may also split work across +/// subagents. They are held to the same list of tools. +pub fn launch_args(config_file: &Path, tool_ids: &[String], subagents: bool) -> Vec { + let mut config = OsString::from("@"); + config.push(config_file); + let mut args: Vec = vec![ + "--acp".into(), + // No tools on GitHub itself. This chat is about the engine. + "--disable-builtin-mcps".into(), + // No instructions picked up from files on disk. + "--no-custom-instructions".into(), + // The model asks in its reply, not through a form this app has no + // place for. + "--no-ask-user".into(), + // The engine's guidance for a model, sent with the MCP handshake. + "--allow-all-mcp-server-instructions".into(), + "--additional-mcp-config".into(), + config, + // The engine decides what may run. The CLI's own prompt for each + // tool call would add a second gate that knows less. + format!("--allow-tool={SERVER_NAME}").into(), + // The model sees the engine's tools and nothing else: no shell, no + // files, no other MCP server the operator has configured. + "--available-tools".into(), + ]; + args.extend(tool_ids.iter().map(OsString::from)); + if subagents { + args.push(SUBAGENT_TOOL.into()); + } + args +} + +#[cfg(test)] +mod tests { + use super::*; + + fn found(explicit: Option<&str>, path: &str, present: &[&str]) -> Result { + let present: Vec = present.iter().map(PathBuf::from).collect(); + find_program( + explicit.map(Path::new), + Some(OsStr::new(path)), + |candidate| present.iter().any(|p| p == candidate), + ) + } + + fn join(dirs: &[&str]) -> String { + std::env::join_paths(dirs) + .unwrap() + .to_string_lossy() + .into_owned() + } + + #[test] + fn a_location_from_settings_is_used_as_given() { + let got = found(Some("/opt/tools/copilot"), "", &["/opt/tools/copilot"]).unwrap(); + assert_eq!(got, PathBuf::from("/opt/tools/copilot")); + } + + #[test] + fn a_wrong_location_from_settings_is_an_error_and_path_is_not_searched() { + let name = program_names()[0]; + let on_path = Path::new("/usr/bin").join(name); + let err = found( + Some("/nowhere/copilot"), + &join(&["/usr/bin"]), + &[on_path.to_str().unwrap()], + ) + .unwrap_err(); + assert!(err.contains("Settings"), "{err}"); + } + + #[test] + fn the_first_directory_on_path_that_has_it_wins() { + let name = program_names()[0]; + let first = Path::new("/a").join(name); + let second = Path::new("/b").join(name); + let got = found( + None, + &join(&["/empty", "/a", "/b"]), + &[first.to_str().unwrap(), second.to_str().unwrap()], + ) + .unwrap(); + assert_eq!(got, first); + } + + #[test] + fn nothing_on_path_says_how_to_fix_it() { + let err = found(None, &join(&["/a", "/b"]), &[]).unwrap_err(); + assert!(err.contains("copilot login"), "{err}"); + assert!(err.contains("Settings"), "{err}"); + } + + #[test] + fn tools_are_named_with_the_server_prefix() { + assert_eq!( + tool_ids(&["run_select_query".to_string(), "list_providers".to_string()]), + vec!["stackql-run_select_query", "stackql-list_providers"] + ); + assert!(tool_ids(&[]).is_empty()); + } + + #[test] + fn the_config_names_one_server_started_the_way_the_engine_says() { + let server = McpServerCommand { + program: PathBuf::from("/usr/local/bin/stackql"), + args: vec!["mcp".into(), "--mcp.config".into(), r#"{"a":"b c"}"#.into()], + cwd: PathBuf::from("/data/approot"), + }; + let config = mcp_config(&server).unwrap(); + let servers = config["mcpServers"].as_object().unwrap(); + assert_eq!(servers.len(), 1); + let entry = &servers[SERVER_NAME]; + assert_eq!(entry["type"], "local"); + assert_eq!(entry["command"], "/usr/local/bin/stackql"); + assert_eq!(entry["args"][2], r#"{"a":"b c"}"#); + assert_eq!(entry["cwd"], "/data/approot"); + } + + #[test] + fn the_command_line_limits_the_agent_to_the_engine() { + let args = launch_args( + Path::new("/data/copilot/mcp-config.json"), + &tool_ids(&["run_select_query".to_string(), "server_info".to_string()]), + false, + ); + let args: Vec = args + .iter() + .map(|a| a.to_string_lossy().into_owned()) + .collect(); + + assert_eq!(args[0], "--acp"); + let at = |flag: &str| args.iter().position(|a| a == flag).unwrap(); + assert_eq!( + args[at("--additional-mcp-config") + 1], + "@/data/copilot/mcp-config.json" + ); + assert!(args.contains(&"--allow-tool=stackql".to_string())); + assert!(args.contains(&"--disable-builtin-mcps".to_string())); + // The tool list is last, because the flag takes every word after it. + assert_eq!( + &args[at("--available-tools") + 1..], + ["stackql-run_select_query", "stackql-server_info"] + ); + // Nothing here may widen what the agent can do. + for forbidden in ["--allow-all", "--yolo", "--allow-all-tools", "--autopilot"] { + assert!(!args.iter().any(|a| a == forbidden), "{forbidden} is set"); + } + } + + #[test] + fn the_agent_is_told_which_kind_of_subagent_can_do_the_work() { + let hint = PROFILE.subagent_hint; + assert!(hint.contains("general-purpose")); + assert!(hint.contains("mode to sync")); + assert!(hint.contains("explore")); + assert!(hint.contains("background")); + } + + #[test] + fn subagents_add_one_tool_and_nothing_else() { + let ids = tool_ids(&["run_select_query".to_string()]); + let file = Path::new("/data/copilot/mcp-config.json"); + let text = |args: Vec| -> Vec { + args.iter() + .map(|a| a.to_string_lossy().into_owned()) + .collect() + }; + let without = text(launch_args(file, &ids, false)); + let with = text(launch_args(file, &ids, true)); + + assert!(!without.contains(&"task".to_string())); + // The same command line, with the subagent tool on the end of the + // list of tools the model may use. + let mut expected = without.clone(); + expected.push("task".to_string()); + assert_eq!(with, expected); + let at = with.iter().position(|a| a == "--available-tools").unwrap(); + assert_eq!(&with[at + 1..], ["stackql-run_select_query", "task"]); + } +} diff --git a/src-tauri/src/agent/delegate.rs b/src-tauri/src/agent/delegate.rs new file mode 100644 index 0000000..aa1781b --- /dev/null +++ b/src-tauri/src/agent/delegate.rs @@ -0,0 +1,1728 @@ +//! A delegated agent session: an agent the operator installed runs the +//! model and the tools, and this side sends prompts and shows what happens. +//! +//! The agent is its own MCP client and starts the engine's MCP server +//! itself, in the workspace safety mode. The engine still decides what may +//! run. Nothing here judges a statement. + +use std::collections::HashMap; +use std::path::Path; +use std::sync::Arc; +use std::time::{Duration, Instant}; + +use serde::Serialize; +use serde_json::{Value, json}; +use tokio::sync::{Notify, mpsc}; + +use super::acp::{ + AUTH_REQUIRED, AcpClient, AcpError, Incoming, METHOD_NOT_FOUND, PROTOCOL_VERSION, +}; +use super::backend::{StopReason, Usage}; +use super::guidance::PRESENTATION; +use super::runtime::{AgentEvent, Emit, MAX_UI_TEXT_CHARS, TurnSummary, table_from_structured}; +use crate::connection::AgentChannel; +use crate::error::{HostError, HostResult}; +use crate::util::truncate; + +/// How long the agent gets to answer the handshake and open a session. +const SETUP_TIMEOUT: Duration = Duration::from_secs(60); +/// How long the agent gets to wind a turn down after it is told to stop. +const CANCEL_GRACE: Duration = Duration::from_secs(15); +const LOG_TAIL_LINES: usize = 12; +/// A turn that starts more subagents than this is stopped. Each one is a +/// model of its own at work, and a subagent that is stuck starts more. +pub const MAX_SUBAGENTS: usize = 12; + +/// Sent ahead of the first message of a session. The agent has its own +/// system prompt, which this app cannot set, so the context goes here. +const PRIMER: &str = "Context for this conversation: you are working inside StackQL Workbench, a \ +desktop tool for querying cloud and SaaS providers with SQL through a local StackQL engine. Work \ +only through the stackql tools.\n\ +- If the engine refuses a statement because it needs approval, do not look for another way to \ +make the same change. Show the SQL and say the operator can run it themselves in the query \ +editor, or change the safety mode. Nothing else can approve it.\n\ +- You never see credentials and you do not need them. If a provider reports missing \ +credentials, say which provider needs them."; + +/// Sent after the primer when the agent may use subagents. Whether to split +/// work, and how, is the client's to say: the engine cannot start agents. +const SUBAGENT_PRIMER: &str = "Subagents: when a request needs several independent lookups, for \ +example the same question asked of different providers, services or resources, you may split \ +the work across subagents with the task tool, one for each independent part, started at the \ +same time.\n\ +- Give each subagent all it needs in its prompt: the provider, what to find out, and to answer \ +with the SQL it ran and a short result. It does not see this conversation.\n\ +- Do not use a subagent for one query, or for a join or a union, which is one statement.\n\ +- Do not use a subagent for anything that changes something. Make changes yourself, one at a \ +time.\n\ +- Start no more than four at once, and tell each one not to start subagents of its own.\n\ +- When they are done, put their findings together in one answer."; + +/// What differs from one agent to the next, apart from how it is started. +#[derive(Debug, Clone, Copy)] +pub struct Profile { + /// The agent's name, for messages to the operator. + pub name: &'static str, + /// What the operator does when the agent is not signed in. + pub sign_in_hint: &'static str, + /// What the agent puts in front of the engine's tool names. + pub tool_prefix: &'static str, + /// The key under which the agent keeps its own additions to protocol + /// messages, such as which subagent a tool call belongs to. + pub vendor_key: &'static str, + /// Events of the agent's own to ask for at the handshake. Empty when + /// there are none. + pub session_events: &'static [&'static str], + /// How to start a subagent with this agent so that it can do the work: + /// which kind and which mode. Added to the guidance on subagents. Empty + /// when the agent needs no such advice. + pub subagent_hint: &'static str, +} + +/// A model the agent offers. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct ModelOption { + pub id: String, + pub name: String, + pub description: String, + /// What a request to this model costs against the operator's plan, as + /// the agent words it, for example "1x". + pub usage: Option, +} + +pub struct DelegateSession { + client: Arc, + incoming: mpsc::UnboundedReceiver, + profile: Profile, + session_id: String, + agent_version: String, + models: Vec, + current_model: Option, + /// The context block has been sent. + primed: bool, + /// The agent was started with its subagent tool. + subagents: bool, + /// A turn was abandoned mid-way, so the session cannot be used again. + broken: bool, +} + +impl DelegateSession { + /// Does the handshake and opens a session in `cwd`. `model` is set when + /// the operator chose one. Otherwise the agent's own choice stands. + pub async fn open( + channel: AgentChannel, + profile: Profile, + cwd: &Path, + model: Option<&str>, + subagents: bool, + ) -> HostResult { + let (client, incoming) = AcpClient::connect(channel); + let name = profile.name; + + let setup = |err: AcpError, client: &AcpClient| match err { + AcpError::Rpc { code, .. } if code == AUTH_REQUIRED => { + HostError::Agent(format!("{name} is not signed in. {}", profile.sign_in_hint)) + } + AcpError::Rpc { message, .. } => { + HostError::Agent(format!("{name} could not start a session: {message}")) + } + AcpError::Closed => HostError::Agent(with_log( + format!("{name} stopped while starting."), + &client.diagnostics_tail(LOG_TAIL_LINES), + )), + }; + let timed_out = |what: &str, client: &AcpClient| { + HostError::Agent(with_log( + format!( + "{name} did not {what} within {} seconds.", + SETUP_TIMEOUT.as_secs() + ), + &client.diagnostics_tail(LOG_TAIL_LINES), + )) + }; + + // No file access and no terminal through this app. The agent gets + // the engine's tools and nothing from the host. + let mut capabilities = json!({ + "fs": { "readTextFile": false, "writeTextFile": false }, + "terminal": false + }); + if !profile.session_events.is_empty() { + // Ask to be told when a subagent starts, so its tool calls can + // be shown as its own and counted. + capabilities["_meta"] = + json!({ profile.vendor_key: { "events": profile.session_events } }); + } + let hello = json!({ + "protocolVersion": PROTOCOL_VERSION, + "clientCapabilities": capabilities, + "clientInfo": { + "name": "stackql-workbench", + "title": "StackQL Workbench", + "version": env!("CARGO_PKG_VERSION") + } + }); + let initialised = tokio::time::timeout(SETUP_TIMEOUT, client.request("initialize", hello)) + .await + .map_err(|_| timed_out("answer", &client))? + .map_err(|err| setup(err, &client))?; + let offered = initialised.get("protocolVersion").and_then(Value::as_u64); + if offered != Some(PROTOCOL_VERSION) { + return Err(HostError::Agent(format!( + "{name} speaks a version of the agent protocol this app does not ({}).", + offered.map_or_else(|| "none".to_string(), |v| v.to_string()) + ))); + } + let agent_version = initialised + .pointer("/agentInfo/version") + .and_then(Value::as_str) + .unwrap_or_default() + .to_string(); + + let Some(cwd) = cwd.to_str() else { + return Err(HostError::Agent(format!( + "The folder for {name} sessions is not valid Unicode: {}", + cwd.display() + ))); + }; + // The engine's MCP server is named on the agent's command line, not + // here. See the launcher for why. + let opened = tokio::time::timeout( + SETUP_TIMEOUT, + client.request("session/new", json!({ "cwd": cwd, "mcpServers": [] })), + ) + .await + .map_err(|_| timed_out("open a session", &client))? + .map_err(|err| setup(err, &client))?; + let Some(session_id) = opened.get("sessionId").and_then(Value::as_str) else { + return Err(HostError::Agent(format!( + "{name} opened a session without an id." + ))); + }; + let session_id = session_id.to_string(); + let models = parse_models(&opened); + let mut current_model = opened + .pointer("/models/currentModelId") + .and_then(Value::as_str) + .map(str::to_string); + + if let Some(model) = model.map(str::trim).filter(|m| !m.is_empty()) { + let set = client + .request( + "session/set_config_option", + json!({ "sessionId": session_id, "configId": "model", "value": model }), + ) + .await; + match set { + Ok(_) => current_model = Some(model.to_string()), + Err(AcpError::Rpc { message, .. }) => { + return Err(HostError::Agent(format!( + "{name} could not use the model \"{model}\": {message}. Choose another in Settings, or clear it to use the agent's own choice." + ))); + } + Err(err) => return Err(setup(err, &client)), + } + } + + Ok(Self { + client, + incoming, + profile, + session_id, + agent_version, + models, + current_model, + primed: false, + subagents, + broken: false, + }) + } + + /// Whether the session can take another prompt. + pub fn is_closed(&self) -> bool { + self.broken || self.client.is_closed() + } + + pub fn agent_version(&self) -> &str { + &self.agent_version + } + + pub fn models(&self) -> &[ModelOption] { + &self.models + } + + pub fn current_model(&self) -> Option<&str> { + self.current_model.as_deref() + } + + /// Runs one turn. Events go to `emit` as the agent works. `stop` asks + /// the agent to cancel. + pub async fn prompt( + &mut self, + text: &str, + stop: &Notify, + emit: &Emit, + ) -> HostResult { + let name = self.profile.name; + let mut blocks = Vec::new(); + if !self.primed { + // The context, then how the work is shown, which is the same + // text the host's own loop puts in its system prompt. + blocks.push(json!({ "type": "text", "text": format!("{PRIMER}\n\n{PRESENTATION}") })); + if self.subagents { + let mut guidance = SUBAGENT_PRIMER.to_string(); + if !self.profile.subagent_hint.is_empty() { + guidance.push('\n'); + guidance.push_str(self.profile.subagent_hint); + } + blocks.push(json!({ "type": "text", "text": guidance })); + } + } + blocks.push(json!({ "type": "text", "text": text })); + self.primed = true; + + let client = self.client.clone(); + let params = json!({ "sessionId": self.session_id, "prompt": blocks }); + let request = client.request("session/prompt", params); + tokio::pin!(request); + + let mut turn = Turn::new(self.profile, self.session_id.clone()); + let mut cancelling = false; + let mut incoming_open = true; + let mut deadline: Option = None; + + let outcome = loop { + let grace = async { + match deadline { + Some(at) => tokio::time::sleep_until(at).await, + None => std::future::pending().await, + } + }; + tokio::select! { + result = &mut request => break Some(result), + item = self.incoming.recv(), if incoming_open => match item { + Some(item) => { + if let Some(reply) = turn.handle(item, emit) { + reply.send(&client).await; + } + // The turn went past a limit of this app's. Stop it + // and say why. + if !cancelling && let Some(reason) = turn.abort.take() { + emit(AgentEvent::Notice { message: reason }); + cancelling = true; + deadline = Some(tokio::time::Instant::now() + CANCEL_GRACE); + let _ = client + .notify("session/cancel", json!({ "sessionId": self.session_id })) + .await; + } + } + None => incoming_open = false, + }, + () = stop.notified(), if !cancelling => { + cancelling = true; + deadline = Some(tokio::time::Instant::now() + CANCEL_GRACE); + let _ = client + .notify("session/cancel", json!({ "sessionId": self.session_id })) + .await; + } + () = grace => break None, + } + }; + + // What the agent sent before its answer is already queued. + while let Ok(item) = self.incoming.try_recv() { + if let Some(reply) = turn.handle(item, emit) { + reply.send(&client).await; + } + } + turn.settle(cancelling, emit); + + let mut summary = TurnSummary { + steps: turn.steps, + tool_calls: turn.tool_calls, + stopped: cancelling, + stop: StopReason::EndTurn, + usage: Usage::default(), + }; + match outcome { + Some(Ok(result)) => { + // The agent adds its model calls up itself and reports the + // turn. Its input count holds what was read from the cache. + let count = |name: &str| { + result + .pointer(&format!("/usage/{name}")) + .and_then(Value::as_u64) + }; + summary.usage = Usage { + input_tokens: count("inputTokens"), + output_tokens: count("outputTokens"), + cached_input_tokens: count("cachedReadTokens"), + }; + match result.get("stopReason").and_then(Value::as_str) { + Some("cancelled") => summary.stopped = true, + Some("max_tokens") => summary.stop = StopReason::MaxTokens, + Some("refusal") => { + summary.stop = + StopReason::Refused("The model declined to answer.".to_string()); + } + Some("max_turn_requests") => { + emit(AgentEvent::Notice { + message: format!( + "{name} reached its limit of model requests for one turn. Ask again to continue." + ), + }); + summary.stop = StopReason::Other("request limit".to_string()); + } + _ => {} + } + Ok(summary) + } + Some(Err(AcpError::Rpc { code, .. })) if code == AUTH_REQUIRED => { + Err(HostError::Agent(format!( + "{name} is not signed in. {}", + self.profile.sign_in_hint + ))) + } + Some(Err(AcpError::Rpc { message, .. })) => Err(HostError::Agent(format!( + "{name} reported an error: {message}" + ))), + Some(Err(AcpError::Closed)) => { + self.broken = true; + Err(HostError::Agent(with_log( + format!("{name} stopped unexpectedly."), + &self.client.diagnostics_tail(LOG_TAIL_LINES), + ))) + } + None => { + // Told to stop and never answered. The prompt is still open + // on its side, so this session is finished. + self.broken = true; + summary.stopped = true; + Ok(summary) + } + } + } +} + +fn with_log(message: String, tail: &[String]) -> String { + if tail.is_empty() { + message + } else { + format!("{message}\n{}", tail.join("\n")) + } +} + +fn parse_models(opened: &Value) -> Vec { + let text = |value: &Value, key: &str| { + value + .get(key) + .and_then(Value::as_str) + .unwrap_or_default() + .to_string() + }; + opened + .pointer("/models/availableModels") + .and_then(Value::as_array) + .map(|models| { + models + .iter() + .filter_map(|model| { + let id = text(model, "modelId"); + (!id.is_empty()).then(|| ModelOption { + name: text(model, "name"), + description: text(model, "description"), + usage: model + .pointer("/_meta/copilotUsage") + .and_then(Value::as_str) + .map(str::to_string), + id, + }) + }) + .collect() + }) + .unwrap_or_default() +} + +/// The name a call that starts a subagent is shown under. +pub const SUBAGENT_TOOL: &str = "subagent"; + +/// An answer owed to the agent. +#[derive(Debug, PartialEq)] +struct Reply { + id: Value, + answer: Result, +} + +impl Reply { + async fn send(self, client: &AcpClient) { + let _ = match self.answer { + Ok(result) => client.respond(self.id, result).await, + Err((code, message)) => client.respond_error(self.id, code, message).await, + }; + } +} + +struct ToolState { + started: Instant, + finished: bool, +} + +/// What has happened in the turn that is running. +struct Turn { + profile: Profile, + session_id: String, + tools: HashMap, + order: Vec, + last_message: Option, + steps: usize, + tool_calls: usize, + /// The subagents seen this turn, by the agent's id for each, with the + /// name shown to the operator. + agents: HashMap, + /// Set when this app has to stop the turn, with the reason. + abort: Option, +} + +impl Turn { + fn new(profile: Profile, session_id: String) -> Self { + Self { + profile, + session_id, + tools: HashMap::new(), + order: Vec::new(), + last_message: None, + steps: 0, + tool_calls: 0, + agents: HashMap::new(), + abort: None, + } + } + + /// Notes a subagent and returns the name shown for it. More than + /// [`MAX_SUBAGENTS`] in one turn stops the turn. + fn subagent(&mut self, id: &str, name: Option<&str>) -> String { + if let Some(known) = self.agents.get(id) { + return known.clone(); + } + let number = self.agents.len() + 1; + let label = name + .map(str::trim) + .filter(|n| !n.is_empty()) + .map_or_else(|| format!("subagent {number}"), |n| truncate(n, 40)); + self.agents.insert(id.to_string(), label.clone()); + if self.agents.len() > MAX_SUBAGENTS && self.abort.is_none() { + self.abort = Some(format!( + "Stopped: {} started more than {MAX_SUBAGENTS} subagents in one turn. Ask for less at once, or turn subagents off in Settings.", + self.profile.name + )); + } + label + } + + /// The subagent an update belongs to, if it is not the main agent's. + fn agent_of(&mut self, update: &Value) -> Option { + let id = update + .get("_meta")? + .get(self.profile.vendor_key)? + .get("agentId")? + .as_str()? + .to_string(); + Some(self.subagent(&id, None)) + } + + /// One of the agent's own events. Only the start of a subagent is of + /// interest: it gives the subagent's name before its first tool call. + fn session_event(&mut self, params: &Value) { + if params.get("sessionId").and_then(Value::as_str) != Some(&self.session_id) + || params.get("type").and_then(Value::as_str) != Some("subagent.started") + { + return; + } + let Some(id) = params.get("agentId").and_then(Value::as_str) else { + return; + }; + let name = params + .pointer("/data/agentDisplayName") + .and_then(Value::as_str); + let id = id.to_string(); + self.subagent(&id, name); + + // A subagent that starts a subagent was told not to. In testing it + // was always one that could not do its job and tried to hand it on, + // four deep, at a cost in time and no gain. Stop at the first. + let nested = params + .pointer("/data/parentId") + .is_some_and(|parent| !parent.is_null()); + if nested && self.abort.is_none() { + self.abort = Some(format!( + "Stopped: a {} subagent started a subagent of its own, which usually means it could not do what it was asked. Ask again in smaller steps, or turn subagents off in Settings.", + self.profile.name + )); + } + } + + /// Takes one message from the agent. Returns the answer when the + /// message was a request. + fn handle(&mut self, item: Incoming, emit: &Emit) -> Option { + match item { + Incoming::Notification { method, params } => { + if method == "session/update" + && params.get("sessionId").and_then(Value::as_str) == Some(&self.session_id) + && let Some(update) = params.get("update") + { + self.update(update, emit); + } else if method.strip_suffix("/sessionEvent") == Some(self.profile.vendor_key) { + self.session_event(¶ms); + } + None + } + Incoming::Request { id, method, params } => Some(match method.as_str() { + "session/request_permission" => self.permission(id, ¶ms, emit), + // No capability for anything else was advertised. + _ => Reply { + id, + answer: Err((METHOD_NOT_FOUND, "Method not found")), + }, + }), + } + } + + /// The agent asks whether it may run something. The engine's tools are + /// allowed on its command line and never ask, so this is the agent + /// reaching for something else. The answer is no, and the operator is + /// told. Nothing is ever approved on the operator's behalf. + fn permission(&mut self, id: Value, params: &Value, emit: &Emit) -> Reply { + let what = params + .pointer("/toolCall/title") + .and_then(Value::as_str) + .unwrap_or("something"); + emit(AgentEvent::Notice { + message: format!( + "{} asked for permission to run \"{}\", which is not one of the engine's tools. It was declined.", + self.profile.name, + truncate(what, 200) + ), + }); + let reject = params + .get("options") + .and_then(Value::as_array) + .and_then(|options| { + options + .iter() + .find(|o| o.get("kind").and_then(Value::as_str) == Some("reject_once")) + }) + .and_then(|option| option.get("optionId")) + .cloned(); + let outcome = match reject { + Some(option) => json!({ "outcome": "selected", "optionId": option }), + None => json!({ "outcome": "cancelled" }), + }; + Reply { + id, + answer: Ok(json!({ "outcome": outcome })), + } + } + + fn update(&mut self, update: &Value, emit: &Emit) { + match update.get("sessionUpdate").and_then(Value::as_str) { + Some("agent_message_chunk") => { + // What a subagent writes is its report to the agent that + // started it. It arrives whole as the result of that call, + // so the pieces are not shown as the assistant's own words. + if self.agent_of(update).is_some() { + return; + } + let Some(text) = update.pointer("/content/text").and_then(Value::as_str) else { + return; + }; + match update.get("messageId").and_then(Value::as_str) { + Some(message) => { + if self.last_message.as_deref() != Some(message) { + self.last_message = Some(message.to_string()); + self.steps += 1; + } + emit(AgentEvent::AssistantDelta { + id: message.to_string(), + text: text.to_string(), + }); + } + // A line from the agent program itself, not the model. + None => { + let line = text.trim(); + let line = line.strip_prefix("Info: ").unwrap_or(line); + // It lists the tools it turned off at every start, + // which is this app's doing and not news. + if !line.is_empty() && !line.starts_with("Disabled tools:") { + emit(AgentEvent::Notice { + message: format!("{}: {line}", self.profile.name), + }); + } + } + } + } + Some("tool_call") => { + let Some(id) = update.get("toolCallId").and_then(Value::as_str) else { + return; + }; + if !self.tools.contains_key(id) { + let title = update + .get("title") + .and_then(Value::as_str) + .unwrap_or("tool"); + let raw = update.get("rawInput").cloned().unwrap_or(Value::Null); + // Whose call it is: the main agent's, or a subagent's. + let agent = self.agent_of(update); + self.tools.insert( + id.to_string(), + ToolState { + started: Instant::now(), + finished: false, + }, + ); + self.order.push(id.to_string()); + self.tool_calls += 1; + // The call that starts a subagent names the kind of + // agent. Show it as a subagent with its task, not as a + // tool with a page of arguments. + let (tool, arguments) = if raw.get("agent_type").is_some() { + let task = raw + .get("description") + .and_then(Value::as_str) + .unwrap_or(title); + (SUBAGENT_TOOL.to_string(), json!({ "task": task })) + } else { + ( + title + .strip_prefix(self.profile.tool_prefix) + .unwrap_or(title) + .to_string(), + raw, + ) + }; + emit(AgentEvent::ToolCallStarted { + id: id.to_string(), + tool, + sql: arguments + .get("sql") + .and_then(Value::as_str) + .map(str::to_string), + arguments, + agent, + // The agent does not say where one of its model's + // steps ends. A message of its own does: the calls + // that follow one belong together. + step: self.steps, + }); + } + self.finish_if_done(id, update, emit); + } + Some("tool_call_update") => { + if let Some(id) = update.get("toolCallId").and_then(Value::as_str) { + self.finish_if_done(id, update, emit); + } + } + // Thoughts, plans, usage and the agent's own bookkeeping are + // not shown. + _ => {} + } + } + + fn finish_if_done(&mut self, id: &str, update: &Value, emit: &Emit) { + let failed = match update.get("status").and_then(Value::as_str) { + Some("completed") => false, + Some("failed") => true, + _ => return, + }; + let Some(state) = self.tools.get_mut(id) else { + return; + }; + if state.finished { + return; + } + state.finished = true; + let elapsed_ms = u64::try_from(state.started.elapsed().as_millis()).unwrap_or(u64::MAX); + emit(AgentEvent::ToolCallFinished { + id: id.to_string(), + is_error: failed, + text: truncate(&result_text(update, failed), MAX_UI_TEXT_CHARS), + table: update + .pointer("/rawOutput/structuredContent") + .and_then(table_from_structured), + // The engine's stderr goes to the agent, not to this app, so + // there is nothing to report here. + engine_notes: Vec::new(), + elapsed_ms, + }); + } + + /// Closes the tool calls the agent never reported a result for. + fn settle(&mut self, stopped: bool, emit: &Emit) { + for id in &self.order { + let Some(state) = self.tools.get_mut(id) else { + continue; + }; + if state.finished { + continue; + } + state.finished = true; + emit(AgentEvent::ToolCallFinished { + id: id.clone(), + is_error: true, + text: if stopped { + "Stopped. The engine cannot cancel a statement, so it may still complete." + .to_string() + } else { + format!("{} reported no result for this call.", self.profile.name) + }, + table: None, + engine_notes: Vec::new(), + elapsed_ms: u64::try_from(state.started.elapsed().as_millis()).unwrap_or(u64::MAX), + }); + } + } +} + +/// The text of a tool result, as the engine rendered it. +fn result_text(update: &Value, failed: bool) -> String { + if failed && let Some(message) = update.pointer("/rawOutput/message").and_then(Value::as_str) { + return message.to_string(); + } + let joined = |items: Option<&Value>, path: &str| { + let parts: Vec<&str> = items + .and_then(Value::as_array)? + .iter() + .filter_map(|item| item.pointer(path).and_then(Value::as_str)) + .collect(); + (!parts.is_empty()).then(|| parts.join("\n")) + }; + // The engine's own text blocks, without the copy of the payload the + // agent appends for the model. + joined(update.pointer("/rawOutput/contents"), "/text") + .or_else(|| joined(update.get("content"), "/content/text")) + .or_else(|| { + update + .pointer("/rawOutput/content") + .and_then(Value::as_str) + .map(str::to_string) + }) + .unwrap_or_default() +} + +#[cfg(test)] +mod tests { + use std::sync::Mutex; + + use super::super::acp::testing::FakeAgent; + use super::*; + use crate::connection::LogBuffer; + + const PROFILE: Profile = Profile { + name: "Test Agent", + sign_in_hint: "Run `agent login`.", + tool_prefix: "stackql-", + vendor_key: "example.com/agent", + session_events: &["subagent.started"], + subagent_hint: "- Use the plain kind of subagent.", + }; + + /// An update tagged as a subagent's. + fn by(agent: &str, mut update: Value) -> Value { + update["_meta"] = json!({ "example.com/agent": { "agentId": agent } }); + update + } + + fn collector() -> (Emit, Arc>>) { + let events: Arc>> = Arc::default(); + let sink = events.clone(); + let emit: Emit = Arc::new(move |event| sink.lock().unwrap().push(event)); + (emit, events) + } + + /// A session wired to a scripted agent, past the handshake. + async fn opened(model: Option<&'static str>) -> (DelegateSession, FakeAgent) { + let (ours, theirs) = tokio::io::duplex(1 << 16); + let (our_read, our_write) = tokio::io::split(ours); + let channel = AgentChannel { + reader: Box::new(our_read), + writer: Box::new(our_write), + diagnostics: LogBuffer::default(), + keepalive: Box::new(()), + }; + let mut agent = FakeAgent::over(theirs); + let opening = tokio::spawn(async move { + DelegateSession::open(channel, PROFILE, Path::new("/work"), model, true).await + }); + + let (id, params) = agent.expect("initialize").await; + assert_eq!(params["protocolVersion"], 1); + assert_eq!(params["clientCapabilities"]["terminal"], false); + assert_eq!(params["clientCapabilities"]["fs"]["writeTextFile"], false); + // The agent's own events are asked for under its own key. + assert_eq!( + params["clientCapabilities"]["_meta"]["example.com/agent"]["events"], + json!(["subagent.started"]) + ); + agent + .result( + id, + json!({ "protocolVersion": 1, "agentInfo": { "name": "T", "version": "9.9" } }), + ) + .await; + + let (id, params) = agent.expect("session/new").await; + assert_eq!(params["cwd"], "/work"); + assert_eq!(params["mcpServers"], json!([])); + agent + .result( + id, + json!({ + "sessionId": "s1", + "models": { + "currentModelId": "small", + "availableModels": [ + { "modelId": "small", "name": "Small", "description": "Cheap", + "_meta": { "copilotUsage": "0.33x" } }, + { "modelId": "big", "name": "Big", "description": "Dear" } + ] + } + }), + ) + .await; + + if let Some(model) = model { + let (id, params) = agent.expect("session/set_config_option").await; + assert_eq!(params["configId"], "model"); + assert_eq!(params["value"], model); + agent.result(id, json!({})).await; + } + (opening.await.unwrap().unwrap(), agent) + } + + #[tokio::test] + async fn opening_reads_the_version_and_the_models() { + let (session, _agent) = opened(None).await; + assert_eq!(session.agent_version(), "9.9"); + assert_eq!(session.current_model(), Some("small")); + assert_eq!( + session.models(), + [ + ModelOption { + id: "small".into(), + name: "Small".into(), + description: "Cheap".into(), + usage: Some("0.33x".into()), + }, + ModelOption { + id: "big".into(), + name: "Big".into(), + description: "Dear".into(), + usage: None, + }, + ] + ); + assert!(!session.is_closed()); + } + + #[tokio::test] + async fn a_chosen_model_is_set_on_the_session() { + let (session, _agent) = opened(Some("big")).await; + assert_eq!(session.current_model(), Some("big")); + } + + #[tokio::test] + async fn an_agent_that_is_not_signed_in_says_how_to_sign_in() { + let (client_side, agent_side) = tokio::io::duplex(1 << 16); + let (read, write) = tokio::io::split(client_side); + let channel = AgentChannel { + reader: Box::new(read), + writer: Box::new(write), + diagnostics: LogBuffer::default(), + keepalive: Box::new(()), + }; + let mut agent = FakeAgent::over(agent_side); + let opening = tokio::spawn(async move { + DelegateSession::open(channel, PROFILE, Path::new("/work"), None, false).await + }); + let (id, _) = agent.expect("initialize").await; + agent.result(id, json!({ "protocolVersion": 1 })).await; + let (id, _) = agent.expect("session/new").await; + agent + .error(id, AUTH_REQUIRED, "Authentication required") + .await; + + let err = opening.await.unwrap().err().unwrap(); + let text = err.to_string(); + assert!(text.contains("not signed in"), "{text}"); + assert!(text.contains("agent login"), "{text}"); + } + + #[tokio::test] + async fn an_agent_on_another_protocol_version_is_refused() { + let (client_side, agent_side) = tokio::io::duplex(1 << 16); + let (read, write) = tokio::io::split(client_side); + let channel = AgentChannel { + reader: Box::new(read), + writer: Box::new(write), + diagnostics: LogBuffer::default(), + keepalive: Box::new(()), + }; + let mut agent = FakeAgent::over(agent_side); + let opening = tokio::spawn(async move { + DelegateSession::open(channel, PROFILE, Path::new("/work"), None, false).await + }); + let (id, _) = agent.expect("initialize").await; + agent.result(id, json!({ "protocolVersion": 2 })).await; + let err = opening.await.unwrap().err().unwrap(); + assert!(err.to_string().contains("version"), "{err}"); + } + + #[tokio::test] + async fn a_turn_streams_text_and_reports_tool_calls() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Arc::new(Notify::new()); + let turn = tokio::spawn({ + let stop = stop.clone(); + async move { + let summary = session.prompt("how many providers?", &stop, &emit).await; + (session, summary) + } + }); + + let (prompt_id, params) = agent.expect("session/prompt").await; + assert_eq!(params["sessionId"], "s1"); + // The first prompt carries the context, how to use subagents, then + // the operator's words. + let blocks = params["prompt"].as_array().unwrap(); + assert_eq!(blocks.len(), 3); + let context = blocks[0]["text"].as_str().unwrap(); + assert!(context.contains("StackQL Workbench")); + // How the work is shown, and how to ask for a chart, come with it. + assert!(context.contains("How your work is shown")); + assert!(context.contains("```chart")); + let guidance = blocks[1]["text"].as_str().unwrap(); + assert!(guidance.starts_with("Subagents:")); + // What this agent needs to be told about its own subagents follows. + assert!(guidance.ends_with("- Use the plain kind of subagent.")); + assert_eq!(blocks[2]["text"], "how many providers?"); + + // The agent's own line about disabled tools is not news. + agent + .update( + "s1", + json!({ "sessionUpdate": "agent_message_chunk", + "content": { "type": "text", "text": "Info: Disabled tools: edit, view" } }), + ) + .await; + agent + .update( + "s1", + json!({ "sessionUpdate": "agent_thought_chunk", + "content": { "type": "text", "text": "thinking" } }), + ) + .await; + for piece in ["Let me ", "check."] { + agent + .update( + "s1", + json!({ "sessionUpdate": "agent_message_chunk", "messageId": "m1", + "content": { "type": "text", "text": piece } }), + ) + .await; + } + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call", "toolCallId": "t1", + "title": "stackql-run_select_query", "kind": "execute", "status": "pending", + "rawInput": { "sql": "SHOW PROVIDERS" } }), + ) + .await; + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call_update", "toolCallId": "t1", "status": "completed", + "content": [{ "type": "content", "content": { "type": "text", + "text": "| name |\n|---|\n| github |\n\n\n{\"rows\":[{\"name\":\"github\"}]}" } }], + "rawOutput": { + "contents": [{ "type": "text", "text": "| name |\n|---|\n| github |\n" }], + "structuredContent": { "rows": [{ "name": "github" }] } + } }), + ) + .await; + // An update for some other session is not this turn's business. + agent + .update( + "other", + json!({ "sessionUpdate": "agent_message_chunk", "messageId": "x", + "content": { "type": "text", "text": "not ours" } }), + ) + .await; + agent + .update( + "s1", + json!({ "sessionUpdate": "agent_message_chunk", "messageId": "m2", + "content": { "type": "text", "text": "One provider." } }), + ) + .await; + agent + .result( + prompt_id, + json!({ "stopReason": "end_turn", + "usage": { "inputTokens": 19353, "outputTokens": 92, "totalTokens": 19445, + "thoughtTokens": 46, "cachedReadTokens": 9533, "cachedWriteTokens": 9805 } }), + ) + .await; + + let (mut session, summary) = turn.await.unwrap(); + let summary = summary.unwrap(); + assert!(!summary.stopped); + assert_eq!(summary.stop, StopReason::EndTurn); + assert_eq!(summary.tool_calls, 1); + assert_eq!(summary.steps, 2); + // The shape the Copilot CLI sent when it was asked. See the spike report. + assert_eq!(summary.usage.input_tokens, Some(19_353)); + assert_eq!(summary.usage.output_tokens, Some(92)); + assert_eq!(summary.usage.cached_input_tokens, Some(9_533)); + + let events = events.lock().unwrap().clone(); + let deltas: Vec<(&str, &str)> = events + .iter() + .filter_map(|e| match e { + AgentEvent::AssistantDelta { id, text } => Some((id.as_str(), text.as_str())), + _ => None, + }) + .collect(); + assert_eq!( + deltas, + [("m1", "Let me "), ("m1", "check."), ("m2", "One provider.")] + ); + assert!( + !events + .iter() + .any(|e| matches!(e, AgentEvent::Notice { .. })), + "nothing to tell the operator: {events:?}" + ); + let started = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallStarted { + id, + tool, + sql, + step, + .. + } => Some((id.clone(), tool.clone(), sql.clone(), *step)), + _ => None, + }) + .unwrap(); + // The call follows the agent's first message, so it is of step one. + assert_eq!( + started, + ( + "t1".to_string(), + "run_select_query".to_string(), + Some("SHOW PROVIDERS".to_string()), + 1 + ) + ); + let finished = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallFinished { + is_error, + text, + table, + .. + } => Some((*is_error, text.clone(), table.clone())), + _ => None, + }) + .unwrap(); + assert!(!finished.0); + assert!( + !finished.1.contains("\"rows\""), + "the payload copy is left out" + ); + let table = finished.2.unwrap(); + assert_eq!(table.columns, ["name"]); + assert_eq!(table.rows, [[Some("github".to_string())]]); + + // The context is sent once. + let (emit, _) = collector(); + let next = tokio::spawn(async move { session.prompt("and now?", &stop, &emit).await }); + let (id, params) = agent.expect("session/prompt").await; + assert_eq!(params["prompt"].as_array().unwrap().len(), 1); + agent.result(id, json!({ "stopReason": "end_turn" })).await; + next.await.unwrap().unwrap(); + } + + #[tokio::test] + async fn subagents_are_shown_with_their_task_and_their_calls_are_marked() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = + tokio::spawn(async move { session.prompt("audit two providers", &stop, &emit).await }); + let (prompt_id, _) = agent.expect("session/prompt").await; + + // The main agent starts a subagent. + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call", "toolCallId": "task1", + "title": "Count github repos", "kind": "other", "status": "pending", + "rawInput": { "name": "github-count", "agent_type": "task", + "description": "Count github repos", + "prompt": "A long prompt the operator does not need to read.", + "mode": "sync" } }), + ) + .await; + agent + .send(json!({ + "jsonrpc": "2.0", "method": "example.com/agent/sessionEvent", + "params": { "sessionId": "s1", "type": "subagent.started", "agentId": "a1", + "data": { "toolCallId": "task1", "agentDisplayName": "github-count" } } + })) + .await; + // The subagent thinks aloud and runs a query. + agent + .update( + "s1", + by( + "a1", + json!({ "sessionUpdate": "agent_message_chunk", "messageId": "sub-m1", + "content": { "type": "text", "text": "Counting now." } }), + ), + ) + .await; + agent + .update( + "s1", + by( + "a1", + json!({ "sessionUpdate": "tool_call", "toolCallId": "q1", + "title": "stackql-run_select_query", "status": "pending", + "rawInput": { "sql": "SELECT COUNT(*) FROM github.repos.repos" } }), + ), + ) + .await; + agent + .update( + "s1", + by("a1", json!({ "sessionUpdate": "tool_call_update", "toolCallId": "q1", + "status": "completed", + "rawOutput": { "contents": [{ "type": "text", "text": "| n |\n|---|\n| 90 |" }], + "structuredContent": { "rows": [{ "n": 90 }] } } })), + ) + .await; + // Its report comes back as the result of the call that started it. + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call_update", "toolCallId": "task1", + "status": "completed", + "content": [{ "type": "content", + "content": { "type": "text", "text": "github has 90 repos." } }] }), + ) + .await; + agent + .update( + "s1", + json!({ "sessionUpdate": "agent_message_chunk", "messageId": "m1", + "content": { "type": "text", "text": "90 repos in github." } }), + ) + .await; + agent + .result(prompt_id, json!({ "stopReason": "end_turn" })) + .await; + let summary = turn.await.unwrap().unwrap(); + assert!(!summary.stopped); + assert_eq!(summary.tool_calls, 2); + + let events = events.lock().unwrap().clone(); + let started: Vec<_> = events + .iter() + .filter_map(|e| match e { + AgentEvent::ToolCallStarted { + id, + tool, + arguments, + agent, + .. + } => Some((id.as_str(), tool.as_str(), arguments.clone(), agent.clone())), + _ => None, + }) + .collect(); + // The start of a subagent shows its task and not its whole prompt. + assert_eq!( + started[0], + ( + "task1", + "subagent", + json!({ "task": "Count github repos" }), + None + ) + ); + // The subagent's own call is an engine tool, marked with its name. + assert_eq!(started[1].0, "q1"); + assert_eq!(started[1].1, "run_select_query"); + assert_eq!(started[1].3.as_deref(), Some("github-count")); + + // Only the main agent's words are shown as the reply. + let said: Vec<&str> = events + .iter() + .filter_map(|e| match e { + AgentEvent::AssistantDelta { text, .. } => Some(text.as_str()), + _ => None, + }) + .collect(); + assert_eq!(said, ["90 repos in github."]); + + // The subagent's report is the result of the call that started it. + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::ToolCallFinished { id, is_error: false, text, .. } + if id == "task1" && text == "github has 90 repos." + ))); + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::ToolCallFinished { id, table: Some(_), .. } if id == "q1" + ))); + } + + #[tokio::test] + async fn a_subagent_with_no_start_event_still_gets_a_name() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("go", &stop, &emit).await }); + let (prompt_id, _) = agent.expect("session/prompt").await; + for (call, who) in [("q1", "a1"), ("q2", "a2"), ("q3", "a1")] { + agent + .update( + "s1", + by( + who, + json!({ "sessionUpdate": "tool_call", "toolCallId": call, + "title": "stackql-list_providers", "status": "completed", + "rawInput": {} }), + ), + ) + .await; + } + agent + .result(prompt_id, json!({ "stopReason": "end_turn" })) + .await; + turn.await.unwrap().unwrap(); + + let names: Vec> = events + .lock() + .unwrap() + .iter() + .filter_map(|e| match e { + AgentEvent::ToolCallStarted { agent, .. } => Some(agent.clone()), + _ => None, + }) + .collect(); + assert_eq!( + names, + [ + Some("subagent 1".to_string()), + Some("subagent 2".to_string()), + Some("subagent 1".to_string()) + ] + ); + } + + #[tokio::test] + async fn too_many_subagents_stop_the_turn_and_say_why() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("everything", &stop, &emit).await }); + let (prompt_id, _) = agent.expect("session/prompt").await; + + for n in 0..=MAX_SUBAGENTS { + agent + .send(json!({ + "jsonrpc": "2.0", "method": "example.com/agent/sessionEvent", + "params": { "sessionId": "s1", "type": "subagent.started", + "agentId": format!("a{n}"), "data": { "agentDisplayName": format!("part {n}") } } + })) + .await; + } + // One past the limit: this side cancels, once. + let message = agent.receive().await; + assert_eq!(message["method"], "session/cancel"); + assert_eq!(message["params"]["sessionId"], "s1"); + agent + .result(prompt_id, json!({ "stopReason": "cancelled" })) + .await; + + let summary = turn.await.unwrap().unwrap(); + assert!(summary.stopped); + let notices: Vec = events + .lock() + .unwrap() + .iter() + .filter_map(|e| match e { + AgentEvent::Notice { message } => Some(message.clone()), + _ => None, + }) + .collect(); + assert_eq!(notices.len(), 1, "{notices:?}"); + assert!(notices[0].contains("subagents"), "{}", notices[0]); + assert!(notices[0].contains("Settings"), "{}", notices[0]); + } + + #[tokio::test] + async fn a_subagent_that_starts_a_subagent_stops_the_turn() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("count them", &stop, &emit).await }); + let (prompt_id, _) = agent.expect("session/prompt").await; + + // A subagent started by the main agent is fine. + agent + .send(json!({ + "jsonrpc": "2.0", "method": "example.com/agent/sessionEvent", + "params": { "sessionId": "s1", "type": "subagent.started", "agentId": "a1", + "data": { "agentDisplayName": "count" } } + })) + .await; + // One started by that subagent is not. + agent + .send(json!({ + "jsonrpc": "2.0", "method": "example.com/agent/sessionEvent", + "params": { "sessionId": "s1", "type": "subagent.started", "agentId": "a2", + "data": { "agentDisplayName": "count again", "parentId": "a1" } } + })) + .await; + let message = agent.receive().await; + assert_eq!(message["method"], "session/cancel"); + agent + .result(prompt_id, json!({ "stopReason": "cancelled" })) + .await; + + let summary = turn.await.unwrap().unwrap(); + assert!(summary.stopped); + let notices: Vec = events + .lock() + .unwrap() + .iter() + .filter_map(|e| match e { + AgentEvent::Notice { message } => Some(message.clone()), + _ => None, + }) + .collect(); + assert_eq!(notices.len(), 1, "{notices:?}"); + assert!(notices[0].contains("subagent of its own"), "{}", notices[0]); + } + + #[tokio::test] + async fn events_for_another_session_or_of_another_kind_are_ignored() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("go", &stop, &emit).await }); + let (prompt_id, _) = agent.expect("session/prompt").await; + for params in [ + json!({ "sessionId": "other", "type": "subagent.started", "agentId": "x" }), + json!({ "sessionId": "s1", "type": "subagent.completed", "agentId": "y" }), + json!({ "sessionId": "s1", "type": "subagent.started" }), + ] { + agent + .send(json!({ "jsonrpc": "2.0", "method": "example.com/agent/sessionEvent", "params": params })) + .await; + } + // Some other vendor's event with the same ending is not ours. + agent + .send( + json!({ "jsonrpc": "2.0", "method": "elsewhere.org/sessionEvent", + "params": { "sessionId": "s1", "type": "subagent.started", "agentId": "z" } }), + ) + .await; + agent + .update( + "s1", + by( + "a1", + json!({ "sessionUpdate": "tool_call", "toolCallId": "q1", + "title": "stackql-server_info", "status": "completed", "rawInput": {} }), + ), + ) + .await; + agent + .result(prompt_id, json!({ "stopReason": "end_turn" })) + .await; + turn.await.unwrap().unwrap(); + // None of those counted, so the first subagent seen is number one. + let events = events.lock().unwrap().clone(); + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::ToolCallStarted { agent: Some(name), .. } if name == "subagent 1" + ))); + } + + #[tokio::test] + async fn the_subagent_guidance_is_left_out_when_subagents_are_off() { + let (client_side, agent_side) = tokio::io::duplex(1 << 16); + let (read, write) = tokio::io::split(client_side); + let channel = AgentChannel { + reader: Box::new(read), + writer: Box::new(write), + diagnostics: LogBuffer::default(), + keepalive: Box::new(()), + }; + let mut agent = FakeAgent::over(agent_side); + let opening = tokio::spawn(async move { + DelegateSession::open(channel, PROFILE, Path::new("/work"), None, false).await + }); + let (id, _) = agent.expect("initialize").await; + agent.result(id, json!({ "protocolVersion": 1 })).await; + let (id, _) = agent.expect("session/new").await; + agent.result(id, json!({ "sessionId": "s1" })).await; + let mut session = opening.await.unwrap().unwrap(); + + let (emit, _) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("hello", &stop, &emit).await }); + let (prompt_id, params) = agent.expect("session/prompt").await; + let blocks = params["prompt"].as_array().unwrap(); + assert_eq!(blocks.len(), 2); + assert!( + !blocks + .iter() + .any(|b| b["text"].as_str().unwrap().contains("Subagents:")) + ); + agent + .result(prompt_id, json!({ "stopReason": "end_turn" })) + .await; + turn.await.unwrap().unwrap(); + } + + #[tokio::test] + async fn a_refused_statement_is_shown_as_a_failed_tool_call() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("delete it", &stop, &emit).await }); + + let (prompt_id, _) = agent.expect("session/prompt").await; + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call", "toolCallId": "t1", + "title": "stackql-run_mutation_query", "status": "pending", + "rawInput": { "sql": "DELETE FROM x" } }), + ) + .await; + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call_update", "toolCallId": "t1", "status": "failed", + "rawOutput": { "code": "failure", + "message": "refused: server is in 'safe' mode and the MCP client does not support elicitation" } }), + ) + .await; + agent + .result(prompt_id, json!({ "stopReason": "end_turn" })) + .await; + turn.await.unwrap().unwrap(); + + let events = events.lock().unwrap().clone(); + let finished = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallFinished { is_error, text, .. } => { + Some((*is_error, text.clone())) + } + _ => None, + }) + .unwrap(); + assert!(finished.0); + assert!(finished.1.contains("refused"), "{}", finished.1); + // The host raised no approval of its own. + assert!( + !events + .iter() + .any(|e| matches!(e, AgentEvent::ApprovalRequested { .. })) + ); + } + + #[tokio::test] + async fn a_permission_request_is_declined_and_the_operator_is_told() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("run a script", &stop, &emit).await }); + + let (prompt_id, _) = agent.expect("session/prompt").await; + agent + .send(json!({ + "jsonrpc": "2.0", "id": 0, "method": "session/request_permission", + "params": { + "sessionId": "s1", + "toolCall": { "toolCallId": "t9", "title": "rm -rf things", "kind": "execute" }, + "options": [ + { "optionId": "allow_once", "kind": "allow_once", "name": "Allow once" }, + { "optionId": "allow_always", "kind": "allow_always", "name": "Always allow" }, + { "optionId": "reject_once", "kind": "reject_once", "name": "Deny" } + ] + } + })) + .await; + let answer = agent.receive().await; + assert_eq!(answer["id"], 0); + assert_eq!(answer["result"]["outcome"]["outcome"], "selected"); + assert_eq!(answer["result"]["outcome"]["optionId"], "reject_once"); + + // With no way to say no, the answer is cancel, never yes. + agent + .send(json!({ + "jsonrpc": "2.0", "id": 1, "method": "session/request_permission", + "params": { "sessionId": "s1", "toolCall": { "title": "x" }, + "options": [{ "optionId": "allow_once", "kind": "allow_once", "name": "Allow" }] } + })) + .await; + let answer = agent.receive().await; + assert_eq!(answer["result"]["outcome"]["outcome"], "cancelled"); + + // Anything else the agent asks of its client is refused. + agent + .send( + json!({ "jsonrpc": "2.0", "id": 2, "method": "fs/write_text_file", + "params": { "path": "/etc/passwd", "content": "" } }), + ) + .await; + let answer = agent.receive().await; + assert_eq!(answer["error"]["code"], METHOD_NOT_FOUND); + + agent + .result(prompt_id, json!({ "stopReason": "end_turn" })) + .await; + turn.await.unwrap().unwrap(); + + let notices: Vec = events + .lock() + .unwrap() + .iter() + .filter_map(|e| match e { + AgentEvent::Notice { message } => Some(message.clone()), + _ => None, + }) + .collect(); + assert_eq!(notices.len(), 2); + assert!(notices[0].contains("rm -rf things"), "{}", notices[0]); + assert!(notices[0].contains("declined"), "{}", notices[0]); + } + + #[tokio::test] + async fn stopping_cancels_the_turn_and_closes_open_tool_calls() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Arc::new(Notify::new()); + let turn = tokio::spawn({ + let stop = stop.clone(); + async move { + let summary = session.prompt("long one", &stop, &emit).await; + (session, summary) + } + }); + + let (prompt_id, _) = agent.expect("session/prompt").await; + agent + .update( + "s1", + json!({ "sessionUpdate": "tool_call", "toolCallId": "t1", + "title": "stackql-run_select_query", "status": "pending", + "rawInput": { "sql": "SELECT 1" } }), + ) + .await; + // Wait until the tool call has been seen, then stop. + while events.lock().unwrap().is_empty() { + tokio::task::yield_now().await; + } + stop.notify_one(); + + let (id, params) = { + let message = agent.receive().await; + assert_eq!(message["method"], "session/cancel"); + (message.get("id").cloned(), message["params"].clone()) + }; + assert!(id.is_none(), "cancel is a notification"); + assert_eq!(params["sessionId"], "s1"); + agent + .result(prompt_id, json!({ "stopReason": "cancelled" })) + .await; + + let (session, summary) = turn.await.unwrap(); + assert!(summary.unwrap().stopped); + assert!( + !session.is_closed(), + "a cancelled turn leaves the session usable" + ); + let events = events.lock().unwrap().clone(); + let closed = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallFinished { is_error, text, .. } => { + Some((*is_error, text.clone())) + } + _ => None, + }) + .unwrap(); + assert!(closed.0); + assert!(closed.1.contains("Stopped"), "{}", closed.1); + } + + #[tokio::test] + async fn an_agent_that_dies_mid_turn_is_an_error_and_ends_the_session() { + let (mut session, mut agent) = opened(None).await; + let (emit, _) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { + let outcome = session.prompt("hello", &stop, &emit).await; + (session, outcome) + }); + agent.expect("session/prompt").await; + drop(agent); + + let (session, outcome) = turn.await.unwrap(); + let err = outcome.unwrap_err().to_string(); + assert!(err.contains("stopped unexpectedly"), "{err}"); + assert!(session.is_closed()); + } + + #[tokio::test] + async fn a_line_from_the_agent_program_is_shown_as_a_notice() { + let (mut session, mut agent) = opened(None).await; + let (emit, events) = collector(); + let stop = Notify::new(); + let turn = tokio::spawn(async move { session.prompt("hi", &stop, &emit).await }); + let (prompt_id, _) = agent.expect("session/prompt").await; + agent + .update( + "s1", + json!({ "sessionUpdate": "agent_message_chunk", + "content": { "type": "text", + "text": "Info: Unknown tool name in the tool allowlist: \"stackql-x\"" } }), + ) + .await; + agent + .result(prompt_id, json!({ "stopReason": "max_tokens" })) + .await; + let summary = turn.await.unwrap().unwrap(); + assert_eq!(summary.stop, StopReason::MaxTokens); + let events = events.lock().unwrap().clone(); + assert_eq!( + events, + [AgentEvent::Notice { + message: "Test Agent: Unknown tool name in the tool allowlist: \"stackql-x\"" + .to_string() + }] + ); + } +} diff --git a/src-tauri/src/agent/guidance.rs b/src-tauri/src/agent/guidance.rs new file mode 100644 index 0000000..5edf994 --- /dev/null +++ b/src-tauri/src/agent/guidance.rs @@ -0,0 +1,89 @@ +//! What a model is told about how its work is shown. +//! +//! How a result is to be read is the engine's to say, and its MCP server +//! says it. This is about something the engine knows nothing of: what this +//! app draws. A model has to be told that its calls are folded away as +//! steps, which result set the operator is shown, and how to ask for a +//! chart, because drawing is this app's capability and not the engine's. +//! +//! Both ways a turn runs use the same text. The host's own loop puts it in +//! the system prompt. A delegated agent has a system prompt of its own, so +//! it gets the text ahead of the first message. + +/// How the conversation shows a turn, and the chart block. The format of +/// the block is read by `src/lib/chart.ts` in the webview and described in +/// `docs/charts.md`. Keep the three in step. +pub const PRESENTATION: &str = "How your work is shown to the operator:\n\ +- The operator reads your answer. Above it, the calls you made are listed as steps, folded away, \ +each with its SQL and its result.\n\ +- The rows your last statement returned are shown under the steps as a table the operator can \ +sort and download. When you ask for several statements in one step, the rows of each are shown. \ +Do not restate rows. Add interpretation only: what the rows mean, what stands out, what to do \ +next.\n\ +- If your answer holds chart blocks, those are shown in place of those tables, each with its own \ +data table.\n\ +- A call that fails is not shown. Correct it and carry on. Do not describe the attempts and do \ +not quote error text. If something could not be done, say so once, in plain words, with what the \ +operator can do about it.\n\ +- When you propose a statement for the operator to run, show the SQL in a fenced sql block.\n\n\ +Charts: when the operator asks for a chart, a plot, a graph or a trend, or when a picture says it \ +better than rows, put a fenced code block with the language chart in your answer, holding one \ +JSON object. For example:\n\ +```chart\n\ +{\"type\": \"bar\", \"title\": \"Issues created per month\", \"x\": \"month\", \"y\": [\"issues_created\"]}\n\ +```\n\ +- type is one of bar, line, area, pie, scatter and table. Use line or area for a trend over time, \ +bar to compare amounts, pie only for a few parts of one whole, and table to show a result set as \ +a table.\n\ +- x names the column for the horizontal axis, or for the names of the slices. y lists one or more \ +numeric columns. When rows carry a series name in a column, name that column as series and give \ +one column in y.\n\ +- The chart is drawn from the most recent result set that has those columns. Name the columns \ +exactly as the result has them, and shape the result with SQL first (GROUP BY, ORDER BY, column \ +aliases) so that it is ready to draw. Do not repeat the rows in the block.\n\ +- Draw what can be read: a few dozen points at most, and no more than 8 series. For a ranking, \ +take the top rows with ORDER BY and LIMIT.\n\ +- Only when no one result set holds the data, give it in the block: \ +\"data\": [{\"month\": \"2026-01\", \"open\": 3, \"closed\": 5}]\n\ +- Optional members: \"stacked\": true for bar, \"horizontal\": true for bar with long names, \ +\"xLabel\" and \"yLabel\" for axis titles.\n\ +- Never draw a chart out of text characters, and never describe a chart that you did not put in \ +a block."; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_model_is_told_what_the_operator_sees() { + assert!(PRESENTATION.contains("listed as steps")); + assert!(PRESENTATION.contains("sort and download")); + assert!(PRESENTATION.contains("A call that fails is not shown")); + assert!(PRESENTATION.contains("fenced sql block")); + } + + #[test] + fn the_chart_block_is_described_with_an_example_that_is_valid_json() { + let start = PRESENTATION.find("```chart\n").unwrap() + "```chart\n".len(); + let end = start + PRESENTATION[start..].find("\n```").unwrap(); + let example: serde_json::Value = serde_json::from_str(&PRESENTATION[start..end]).unwrap(); + assert_eq!(example["type"], "bar"); + assert_eq!(example["x"], "month"); + assert_eq!(example["y"][0], "issues_created"); + for kind in ["bar", "line", "area", "pie", "scatter", "table"] { + assert!(PRESENTATION.contains(kind), "{kind}"); + } + assert!(PRESENTATION.contains("\"data\": [{")); + } + + #[test] + fn nothing_here_tells_a_model_how_to_read_a_result() { + // That is the engine's to say. This text is about presentation only. + for phrase in ["http", "status code", "retry", "404", "401"] { + assert!( + !PRESENTATION.to_lowercase().contains(phrase), + "{phrase} belongs to the engine's guidance" + ); + } + } +} diff --git a/src-tauri/src/agent/mcp.rs b/src-tauri/src/agent/mcp.rs new file mode 100644 index 0000000..a01f632 --- /dev/null +++ b/src-tauri/src/agent/mcp.rs @@ -0,0 +1,364 @@ +//! The MCP client for the engine's agent channel. +//! +//! Only the agent runtime uses this. The connection supplies the byte +//! streams, so this module does not know or care that they belong to a child +//! process. What the server does on this channel is recorded in +//! `docs/spike-mcp.md`. + +use std::any::Any; +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; + +use rmcp::model::{ + CallToolRequestParams, ClientCapabilities, ClientConfig, ElicitRequestParams, ElicitResult, + ElicitationAction, ElicitationCapability, FormElicitationCapability, Implementation, + ProtocolVersion, +}; +use rmcp::service::{RequestContext, RoleClient, RunningService}; +use rmcp::{ClientHandler, ErrorData, ServiceExt}; +use serde_json::{Map, Value}; + +use super::approvals::{ApprovalDecision, Approvals}; +use super::backend::ToolSpec; +use crate::connection::{AgentChannel, LogBuffer}; +use crate::error::{HostError, HostResult}; +use crate::util::truncate; + +/// The marker on a line the engine writes to stderr with what a provider +/// answered. It is shown to the operator beside the tool result and goes +/// nowhere else. +/// +/// The engine's MCP server deals with provider errors itself. A call that +/// fails comes back as a tool error with the status and whether a retry can +/// help. A lookup that finds nothing comes back as an empty result, because +/// "not found" is a valid answer, and what the provider said is left on +/// stderr. That last line is what this picks up. It is a display of the +/// engine's own output, not a judgement: nothing here decides that a call +/// failed, and nothing is added to what the model receives. +const UPSTREAM_FAILURE_MARKER: &str = "http response status code:"; +const MAX_NOTE_CHARS: usize = 400; +const MAX_NOTES: usize = 5; + +/// The client half of the handshake and of the approval flow. +struct Handler { + approvals: Arc, +} + +impl ClientHandler for Handler { + fn get_info(&self) -> ClientConfig { + // Without the elicitation capability the server refuses every gated + // tool, since it would have nobody to ask. + let mut elicitation = ElicitationCapability::default(); + elicitation.form = Some(FormElicitationCapability::default()); + let mut capabilities = ClientCapabilities::default(); + capabilities.elicitation = Some(elicitation); + + ClientConfig::new( + capabilities, + Implementation::new("stackql-workbench", env!("CARGO_PKG_VERSION")), + ) + // The newest revision with an initialize handshake. On it the server + // sends the approval prompt itself, in the middle of the tool call. + .with_protocol_version(ProtocolVersion::LATEST_WITH_INITIALIZE) + } + + /// The server asks for approval. The operator answers. Nothing here + /// decides on the operator's behalf. + async fn create_elicitation( + &self, + request: ElicitRequestParams, + _context: RequestContext, + ) -> Result { + let message = match request { + ElicitRequestParams::FormElicitationParams { message, .. } => message, + // The engine does not send any other kind. One that cannot be + // shown as an approval card is declined. + _ => return Ok(ElicitResult::new(ElicitationAction::Decline)), + }; + Ok(match self.approvals.ask(message).await { + // The engine's approval form has no fields to fill in. + ApprovalDecision::Accept => { + ElicitResult::new(ElicitationAction::Accept).with_content(Value::Object(Map::new())) + } + ApprovalDecision::Decline => ElicitResult::new(ElicitationAction::Decline), + ApprovalDecision::Cancel => ElicitResult::new(ElicitationAction::Cancel), + }) + } +} + +/// Tells whether a tool call had the server to itself. +/// +/// What a provider answered is read from the server's stderr, which has no +/// way to say which call a line belongs to. When calls overlap, a line +/// cannot be tied to one of them, so it is shown for none. +#[derive(Default)] +struct Overlap { + in_flight: AtomicUsize, + /// More than one call has been in flight since the server was last idle. + crowded: AtomicBool, +} + +impl Overlap { + fn enter(&self) -> Flight<'_> { + if self.in_flight.fetch_add(1, Ordering::SeqCst) > 0 { + self.crowded.store(true, Ordering::SeqCst); + } + Flight { overlap: self } + } +} + +/// One call in flight. Dropping it ends the call, however it ended, so a +/// call that is abandoned half way is not counted for ever. +struct Flight<'a> { + overlap: &'a Overlap, +} + +impl Flight<'_> { + /// True when no other call has been in flight alongside this one. + fn alone(&self) -> bool { + !self.overlap.crowded.load(Ordering::SeqCst) + } +} + +impl Drop for Flight<'_> { + fn drop(&mut self) { + if self.overlap.in_flight.fetch_sub(1, Ordering::SeqCst) == 1 { + self.overlap.crowded.store(false, Ordering::SeqCst); + } + } +} + +/// What a tool call produced. +#[derive(Debug, Clone, PartialEq)] +pub struct ToolResult { + /// The server's rendering for the model. + pub text: String, + /// The typed payload. Row results are `{ "rows": [ ... ] }`. + pub structured: Option, + pub is_error: bool, + /// What a provider answered, as the engine wrote it to stderr while the + /// tool ran. For the operator only. Empty when calls overlapped. + pub engine_notes: Vec, +} + +pub struct McpSession { + service: RunningService, + tools: Vec, + instructions: String, + protocol_version: String, + diagnostics: LogBuffer, + overlap: Overlap, + /// Keeps the channel open for as long as the session lives. + _keepalive: Box, +} + +impl McpSession { + /// Runs the handshake over the channel and reads the tool list. + pub async fn connect(channel: AgentChannel, approvals: Arc) -> HostResult { + let AgentChannel { + reader, + writer, + diagnostics, + keepalive, + } = channel; + + let service = Handler { approvals } + .serve((reader, writer)) + .await + .map_err(|err| { + let tail = diagnostics.tail(8).join("\n"); + HostError::Agent(format!( + "Could not start a session with the engine's MCP server: {err}\n{tail}" + )) + })?; + + let info = service.peer_info(); + let instructions = info + .as_ref() + .and_then(|i| i.instructions.clone()) + .unwrap_or_default(); + let protocol_version = info + .as_ref() + .map(|i| i.protocol_version.to_string()) + .unwrap_or_default(); + + let tools = service + .list_all_tools() + .await + .map_err(|err| HostError::Agent(format!("Could not list the engine's tools: {err}")))? + .into_iter() + .map(|tool| ToolSpec { + name: tool.name.to_string(), + description: tool.description.map(|d| d.to_string()).unwrap_or_default(), + input_schema: Value::Object((*tool.input_schema).clone()), + destructive: tool.annotations.as_ref().and_then(|a| a.destructive_hint), + }) + .collect(); + + Ok(Self { + service, + tools, + instructions, + protocol_version, + diagnostics, + overlap: Overlap::default(), + _keepalive: keepalive, + }) + } + + pub fn tools(&self) -> &[ToolSpec] { + &self.tools + } + + /// Guidance the server wrote for the model. + pub fn instructions(&self) -> &str { + &self.instructions + } + + /// The protocol revision the two sides settled on. + pub fn protocol_version(&self) -> &str { + &self.protocol_version + } + + pub fn is_closed(&self) -> bool { + self.service.is_closed() + } + + /// Calls a tool. A failure the server reports is a result with + /// `is_error` set, which goes back to the model. `Err` means the session + /// itself is no longer usable. + /// + /// Calls may overlap. The server runs them at the same time. + pub async fn call(&self, name: &str, arguments: Map) -> HostResult { + let flight = self.overlap.enter(); + let mark = self.diagnostics.mark(); + let params = CallToolRequestParams::new(name.to_string()).with_arguments(arguments); + let outcome = self.service.call_tool(params).await; + let engine_notes = if flight.alone() { + upstream_notes(&self.diagnostics.since(mark)) + } else { + Vec::new() + }; + + match outcome { + Ok(result) => { + let text = result + .content + .iter() + .filter_map(|block| block.as_text().map(|t| t.text.as_str())) + .collect::>() + .join("\n"); + Ok(ToolResult { + text, + structured: result.structured_content, + is_error: result.is_error.unwrap_or(false), + engine_notes, + }) + } + Err(err) if self.service.is_closed() => Err(HostError::Agent(format!( + "The engine's MCP server stopped: {err}\n{}", + self.diagnostics.tail(8).join("\n") + ))), + // For example an unknown tool. The model can recover from that. + Err(err) => Ok(ToolResult { + text: format!("The tool call failed: {err}"), + structured: None, + is_error: true, + engine_notes, + }), + } + } + + /// Ends the session. The server exits when its input closes. + pub async fn close(self) { + let _ = self.service.cancel().await; + } +} + +/// Picks the lines that report what a provider answered, one short note +/// per line. The response body that follows the status is cut, since it +/// can be a whole web page. +pub fn upstream_notes(lines: &[String]) -> Vec { + lines + .iter() + .filter(|line| line.contains(UPSTREAM_FAILURE_MARKER)) + .take(MAX_NOTES) + .map(|line| truncate(line.trim(), MAX_NOTE_CHARS)) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_call_is_alone_only_when_nothing_else_ran_beside_it() { + let overlap = Overlap::default(); + + let first = overlap.enter(); + assert!(first.alone()); + drop(first); + + // Two at once: neither had the server to itself, whichever ends first. + let a = overlap.enter(); + let b = overlap.enter(); + assert!(!a.alone()); + assert!(!b.alone()); + drop(b); + assert!(!a.alone(), "it overlapped with one that has since ended"); + + // One that starts while the crowd is thinning still overlapped. + let c = overlap.enter(); + drop(a); + assert!(!c.alone()); + drop(c); + + // Idle again, so the next call starts clean. + let after = overlap.enter(); + assert!(after.alone()); + } + + #[test] + fn a_call_abandoned_half_way_is_not_counted_for_ever() { + let overlap = Overlap::default(); + { + // Dropped without finishing, as when the operator stops a turn. + let _abandoned = overlap.enter(); + } + assert!(overlap.enter().alone()); + } + + #[test] + fn upstream_failures_are_picked_out_of_engine_output() { + let lines = vec![ + "sink file: C:\\somewhere\\audit.log".to_string(), + "http response status code: 404, response body: ".to_string(), + "".to_string(), + " ".to_string(), + "http response status code: 401, response body: {\"message\":\"Requires authentication\"}" + .to_string(), + ]; + let notes = upstream_notes(&lines); + assert_eq!(notes.len(), 2); + assert!(notes[0].starts_with("http response status code: 404")); + assert!(notes[1].contains("401")); + } + + #[test] + fn a_long_body_is_cut_and_the_count_is_capped() { + let long = format!( + "http response status code: 500, response body: {}", + "x".repeat(5000) + ); + let lines: Vec = (0..20).map(|_| long.clone()).collect(); + let notes = upstream_notes(&lines); + assert_eq!(notes.len(), MAX_NOTES); + assert!(notes[0].chars().count() <= MAX_NOTE_CHARS + 3); + } + + #[test] + fn ordinary_output_produces_no_notes() { + let lines = vec!["[stackql mcp] starting".to_string(), String::new()]; + assert!(upstream_notes(&lines).is_empty()); + } +} diff --git a/src-tauri/src/agent/mod.rs b/src-tauri/src/agent/mod.rs new file mode 100644 index 0000000..fddb059 --- /dev/null +++ b/src-tauri/src/agent/mod.rs @@ -0,0 +1,20 @@ +//! The agent runtime: the MCP client, the inference backends and the loop. +//! +//! This is the only part of the host that talks to a model, and the only +//! part that uses the engine's agent channel. +//! +//! There are two ways a turn runs. With an API key backend the host runs +//! the loop and is the MCP client. With a delegated agent, an agent the +//! operator installed runs the loop and is the MCP client, and the host +//! drives it over the Agent Client Protocol. + +pub mod acp; +pub mod approvals; +pub mod backend; +pub mod backends; +pub mod copilot; +pub mod delegate; +pub mod guidance; +pub mod mcp; +pub mod runtime; +pub mod turnlog; diff --git a/src-tauri/src/agent/runtime.rs b/src-tauri/src/agent/runtime.rs new file mode 100644 index 0000000..c987615 --- /dev/null +++ b/src-tauri/src/agent/runtime.rs @@ -0,0 +1,1075 @@ +//! The agent loop: conversation, model, tools, approvals. +//! +//! The host runs the loop and owns the MCP client. A turn goes: send the +//! conversation to the model, run the tools it asks for through the engine's +//! MCP server, send the results back, and repeat until the model answers +//! without asking for a tool. +//! +//! Safety is the engine's job. The loop passes the workspace safety mode to +//! the MCP server and relays its approval prompts to the operator. It makes +//! no judgement of its own about any statement. + +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::Instant; + +use futures_util::future::join_all; +use serde::Serialize; +use serde_json::Value; +use tokio::sync::Notify; + +use super::acp::PROTOCOL_VERSION as ACP_VERSION; +use super::approvals::{ApprovalRequest, Approvals}; +use super::backend::{ + ChatRequest, InferenceBackend, Message, StopReason, ToolCall, ToolOutcome, ToolSpec, Usage, +}; +use super::copilot; +use super::delegate::{DelegateSession, ModelOption}; +use super::guidance::PRESENTATION; +use super::mcp::{McpSession, ToolResult}; +use crate::connection::{ + Connection, DelegateBuilder, DelegateCommand, McpServerCommand, SafetyMode, +}; +use crate::error::{HostError, HostResult}; +use crate::query::result::Row; +use crate::util::{lock, truncate}; + +/// A turn that runs this many model calls is stopped. It is far more than a +/// real task needs and guards against a model that never settles. +const MAX_STEPS: usize = 40; +/// Tool output beyond this is cut before it goes to the model. +const MAX_MODEL_CHARS: usize = 60_000; +/// Tool text beyond this is cut before it goes to the webview. The grid +/// shows the rows, so the text is only a preview there. +pub(super) const MAX_UI_TEXT_CHARS: usize = 6_000; +/// Rows beyond this are not sent to the webview for one tool result. +const MAX_UI_ROWS: usize = 5_000; + +const PREAMBLE: &str = "You are the assistant inside StackQL Workbench, a desktop tool for querying \ +cloud and SaaS providers with SQL through a local StackQL engine. You work through the tools \ +provided, which run against that engine.\n\n\ +How to work here:\n\ +- Statements that change something may need the operator's approval. The tool asks for it. If the \ +operator declines, do not try again or look for another way to make the same change. Say what \ +you would have done and stop.\n\ +- You never see credentials and you do not need them. If a provider reports missing credentials, \ +tell the operator which provider needs them."; + +const ENGINE_GUIDANCE_INTRO: &str = + "The engine's own guidance follows. It says how errors and empty results are to be read."; + +/// The system prompt for the host's own loop: who the assistant is, how its +/// work is shown, and then the engine's guidance as the engine wrote it. +fn system_prompt(engine_instructions: &str) -> String { + format!("{PREAMBLE}\n\n{PRESENTATION}\n\n{ENGINE_GUIDANCE_INTRO}\n\n{engine_instructions}") +} + +/// A row result, in the same shape the editor's grid uses. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Table { + pub columns: Vec, + pub rows: Vec, + /// Rows the tool returned, which can be more than were sent on. + pub total_rows: usize, + pub truncated: bool, +} + +/// What the webview is told while a turn runs. +#[derive(Debug, Clone, PartialEq, Serialize)] +#[serde( + rename_all = "camelCase", + rename_all_fields = "camelCase", + tag = "event", + content = "data" +)] +pub enum AgentEvent { + /// A session with the engine's MCP server was opened for this turn. + SessionStarted { + mode: SafetyMode, + protocol_version: String, + tools: usize, + }, + /// A delegated agent was started for this turn. It is its own MCP + /// client, on the engine in the given mode. + DelegateStarted { + mode: SafetyMode, + /// The agent's name, for example "GitHub Copilot CLI". + agent: String, + /// The agent's version. + version: String, + /// The protocol it is driven over, for example "ACP 1". + protocol: String, + /// The model it will use, when it says. + model: Option, + /// How many of the engine's tools it was given. It has no others. + tools: usize, + }, + AssistantText { + text: String, + }, + /// A piece of the reply, as it is written. Pieces with the same id + /// belong to one message. + AssistantDelta { + id: String, + text: String, + }, + ToolCallStarted { + id: String, + tool: String, + arguments: Value, + /// The statement, when the tool takes one. Shown as SQL. + sql: Option, + /// The subagent that made the call, when it was not the main agent. + #[serde(skip_serializing_if = "Option::is_none")] + agent: Option, + /// Which of the model's steps in this turn asked for the call, so + /// that calls asked for together can be shown together. The host's + /// own loop knows each step. A delegated agent's steps are told + /// apart by the message that goes before the calls. + step: usize, + }, + /// The engine wants the operator's approval before it runs something. + ApprovalRequested { + request: ApprovalRequest, + }, + ToolCallFinished { + id: String, + is_error: bool, + text: String, + table: Option, + /// Provider API failures the engine reported while the tool ran. + engine_notes: Vec, + elapsed_ms: u64, + }, + Notice { + message: String, + }, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct TurnSummary { + /// Calls made to the model. + pub steps: usize, + pub tool_calls: usize, + /// The operator stopped the turn. + pub stopped: bool, + pub stop: StopReason, + pub usage: Usage, +} + +pub type Emit = Arc; + +/// How the operator set a delegated agent up. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct DelegateRequest { + /// The model to ask the agent for. `None` leaves the agent's own choice. + pub model: Option, + /// Where the agent's program is. `None` searches `PATH`. + pub program: Option, + /// Whether the agent may split work across subagents. + pub subagents: bool, +} + +/// What a delegated agent says about itself. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct DelegateInfo { + pub version: String, + pub current_model: Option, + pub models: Vec, +} + +/// What a delegated session was started with. A change in any of it needs +/// a new session, because the safety mode is fixed on the agent's command +/// line. +#[derive(PartialEq, Eq)] +struct DelegateKey { + mode: SafetyMode, + request: DelegateRequest, +} + +#[derive(Default)] +struct State { + session: Option<(SafetyMode, McpSession)>, + messages: Vec, + delegate: Option<(DelegateKey, DelegateSession)>, +} + +pub struct AgentRuntime { + connection: Arc, + approvals: Arc, + state: tokio::sync::Mutex, + stop: Mutex>>, + /// Where a delegated agent's configuration and working folder go. + delegate_dir: Option, +} + +/// Undoes the per-turn wiring when a turn ends, however it ends. +struct TurnGuard<'a> { + runtime: &'a AgentRuntime, +} + +impl Drop for TurnGuard<'_> { + fn drop(&mut self) { + *lock(&self.runtime.stop) = None; + self.runtime.approvals.set_listener(None); + // A prompt nobody can answer any more must not stay open. + self.runtime.approvals.cancel_all(); + } +} + +impl AgentRuntime { + pub fn new(connection: Arc) -> Self { + Self { + connection, + approvals: Arc::new(Approvals::default()), + state: tokio::sync::Mutex::new(State::default()), + stop: Mutex::new(None), + delegate_dir: None, + } + } + + /// Sets the folder a delegated agent works in. Without it there are no + /// delegated agents. + pub fn with_delegate_dir(mut self, dir: PathBuf) -> Self { + self.delegate_dir = Some(dir); + self + } + + pub fn approvals(&self) -> &Arc { + &self.approvals + } + + /// Asks the running turn to stop. Returns false if no turn is running. + /// + /// An open approval prompt is answered with cancel. A statement the + /// engine has already started is not interrupted by this. + pub fn stop(&self) -> bool { + let stop = lock(&self.stop).clone(); + match stop { + Some(stop) => { + signal_stop(&stop); + self.approvals.cancel_all(); + true + } + None => false, + } + } + + /// Forgets the conversation and closes the engine session. + pub async fn reset(&self) { + self.stop(); + let mut state = self.state.lock().await; + state.messages.clear(); + if let Some((_, session)) = state.session.take() { + session.close().await; + } + // Dropping the session ends the agent's process. + state.delegate = None; + } + + /// Starts a delegated agent on the engine in the given mode. Returns + /// the session and the number of engine tools the agent was given. + async fn open_delegate( + &self, + request: &DelegateRequest, + mode: SafetyMode, + ) -> HostResult<(DelegateSession, usize)> { + let dir = self.delegate_dir.clone().ok_or_else(|| { + HostError::Agent("No folder for agent sessions is set up.".to_string()) + })?; + let workspace = dir.join("workspace"); + std::fs::create_dir_all(&workspace).map_err(|err| { + HostError::Agent(format!( + "Could not create the folder for agent sessions {}: {err}", + workspace.display() + )) + })?; + let program = copilot::find_program( + request.program.as_deref(), + std::env::var_os("PATH").as_deref(), + copilot::program_exists, + ) + .map_err(HostError::Agent)?; + + // The agent is given the engine's tools by name and no others. The + // names come from the engine, so a new tool in a later engine is + // not left out, and an old one is not asked for. + let channel = self + .connection + .open_agent_channel(SafetyMode::ReadOnly) + .await?; + let probe = McpSession::connect(channel, self.approvals.clone()).await?; + let tools: Vec = probe.tools().iter().map(|tool| tool.name.clone()).collect(); + probe.close().await; + let tool_ids = copilot::tool_ids(&tools); + + // One file per safety mode, so two instances of the app in different + // modes cannot hand each other's mode to an agent that is starting. + let config_file = dir.join(format!("mcp-config-{}.json", mode.as_str())); + let subagents = request.subagents; + let cwd = workspace.clone(); + let build: DelegateBuilder<'_> = Box::new(move |server: McpServerCommand| { + let config = copilot::mcp_config(&server).map_err(HostError::Agent)?; + let text = serde_json::to_string_pretty(&config) + .map_err(|err| HostError::Agent(err.to_string()))?; + // The file holds paths and the safety mode. No secret is in it. + std::fs::write(&config_file, text).map_err(|err| { + HostError::Agent(format!( + "Could not write the agent's configuration {}: {err}", + config_file.display() + )) + })?; + Ok(DelegateCommand { + program, + args: copilot::launch_args(&config_file, &tool_ids, subagents), + cwd, + }) + }); + let channel = self.connection.open_delegate_channel(mode, build).await?; + let session = DelegateSession::open( + channel, + copilot::PROFILE, + &workspace, + request.model.as_deref(), + request.subagents, + ) + .await?; + Ok((session, tools.len())) + } + + /// Asks a delegated agent which models it offers. The session opened + /// for the question is closed again, and no prompt is sent. + pub async fn delegate_info( + &self, + request: DelegateRequest, + mode: SafetyMode, + ) -> HostResult { + let (session, _) = self.open_delegate(&request, mode).await?; + Ok(DelegateInfo { + version: session.agent_version().to_string(), + current_model: session.current_model().map(str::to_string), + models: session.models().to_vec(), + }) + } + + /// Runs one turn through a delegated agent. The agent runs the model + /// and calls the engine's tools itself. The engine applies the safety + /// mode, and what it refuses stays refused: there is no approval prompt + /// on this path, because the agent does not pass one on. + pub async fn send_delegated( + &self, + request: DelegateRequest, + mode: SafetyMode, + text: String, + emit: Emit, + ) -> HostResult { + let mut state = self.state.try_lock().map_err(|_| { + HostError::Agent("The assistant is still working on the previous message.".to_string()) + })?; + let stop = Arc::new(Notify::new()); + *lock(&self.stop) = Some(stop.clone()); + let _guard = TurnGuard { runtime: self }; + + let key = DelegateKey { mode, request }; + let reusable = state + .delegate + .as_ref() + .is_some_and(|(current, session)| *current == key && !session.is_closed()); + if !reusable { + let previous = state.delegate.take().map(|(old, _)| old.mode); + let (session, tools) = self.open_delegate(&key.request, mode).await?; + if let Some(old_mode) = previous { + let cause = if old_mode == mode { + "The previous session ended" + } else { + "The safety mode changed" + }; + emit(AgentEvent::Notice { + message: format!( + "{cause}, so {} started a new session. It does not remember the earlier messages.", + copilot::PROFILE.name + ), + }); + } + let version = session.agent_version(); + emit(AgentEvent::DelegateStarted { + mode, + agent: format!("{} CLI", copilot::PROFILE.name), + version: version.to_string(), + protocol: format!("ACP {ACP_VERSION}"), + model: session.current_model().map(str::to_string), + tools, + }); + state.delegate = Some((key, session)); + } + let Some((_, session)) = state.delegate.as_mut() else { + return Err(HostError::Agent("No agent session.".to_string())); + }; + + let outcome = session.prompt(&text, &stop, &emit).await; + if session.is_closed() { + state.delegate = None; + } + outcome + } + + /// Runs one turn: the operator's message, then model and tool steps + /// until the model answers. + pub async fn send( + &self, + backend: Arc, + mode: SafetyMode, + text: String, + emit: Emit, + ) -> HostResult { + let mut state = self.state.try_lock().map_err(|_| { + HostError::Agent("The assistant is still working on the previous message.".to_string()) + })?; + + let stop = Arc::new(Notify::new()); + *lock(&self.stop) = Some(stop.clone()); + let listener = emit.clone(); + self.approvals.set_listener(Some(Box::new(move |request| { + listener(AgentEvent::ApprovalRequested { request }); + }))); + let _guard = TurnGuard { runtime: self }; + + let State { + session, messages, .. + } = &mut *state; + + // A session is tied to the safety mode it was started with. + let reusable = session + .as_ref() + .is_some_and(|(current, s)| *current == mode && !s.is_closed()); + if !reusable { + if let Some((_, old)) = session.take() { + old.close().await; + } + let channel = self.connection.open_agent_channel(mode).await?; + let fresh = McpSession::connect(channel, self.approvals.clone()).await?; + emit(AgentEvent::SessionStarted { + mode, + protocol_version: fresh.protocol_version().to_string(), + tools: fresh.tools().len(), + }); + *session = Some((mode, fresh)); + } + let Some((_, mcp)) = session.as_ref() else { + return Err(HostError::Agent("No engine session.".to_string())); + }; + + let system = system_prompt(mcp.instructions()); + let turn_start = messages.len(); + messages.push(Message::User { text }); + + let mut summary = TurnSummary { + steps: 0, + tool_calls: 0, + stopped: false, + stop: StopReason::EndTurn, + usage: Usage::default(), + }; + + loop { + if summary.steps >= MAX_STEPS { + emit(AgentEvent::Notice { + message: format!( + "Stopped after {MAX_STEPS} steps without a final answer. Ask again to continue." + ), + }); + summary.stop = StopReason::Other("step limit".to_string()); + break; + } + + let request = ChatRequest { + system: &system, + messages, + tools: mcp.tools(), + }; + let reply = tokio::select! { + reply = backend.complete(request) => Some(reply), + () = stop.notified() => None, + }; + let Some(reply) = reply else { + summary.stopped = true; + messages.push(stopped_message()); + break; + }; + let reply = match reply { + Ok(reply) => reply, + Err(err) => { + // Nothing came back for this message, so take it out + // again. The operator can send it once more. + if summary.steps == 0 { + messages.truncate(turn_start); + } + return Err(HostError::Agent(err.to_string())); + } + }; + + summary.steps += 1; + // A turn's use is that of every call to the model in it. Each + // call sends the conversation again, so the input adds up fast. + summary.usage = summary.usage.plus(reply.usage); + summary.stop = reply.stop.clone(); + if !reply.text.trim().is_empty() { + emit(AgentEvent::AssistantText { + text: reply.text.clone(), + }); + } + let calls = reply.tool_calls.clone(); + messages.push(reply.into_message()); + if calls.is_empty() { + break; + } + + // Calls the engine marks as not destructive run at the same + // time. The rest run alone, in the order the model gave. Results + // go back in the model's order either way. + let mut outcomes = Vec::with_capacity(calls.len()); + for group in groups(&calls, |call| runs_with_others(mcp.tools(), &call.name)) { + if summary.stopped { + // The provider needs a result for every call it made. + outcomes.extend(group.iter().map(|call| ToolOutcome { + call_id: call.id.clone(), + name: call.name.clone(), + content: "The operator stopped this turn before this tool ran.".to_string(), + is_error: true, + })); + continue; + } + summary.tool_calls += group.len(); + let step = summary.steps; + let results = join_all( + group + .iter() + .map(|call| self.run_tool(mcp, call, step, &stop, &emit)), + ) + .await; + for (call, result) in group.iter().zip(results) { + match result? { + Some(outcome) => outcomes.push(outcome), + None => { + summary.stopped = true; + outcomes.push(ToolOutcome { + call_id: call.id.clone(), + name: call.name.clone(), + content: "The operator stopped this turn before this tool \ + finished. It may still have taken effect." + .to_string(), + is_error: true, + }); + } + } + } + } + messages.push(Message::ToolResults { results: outcomes }); + if summary.stopped { + messages.push(stopped_message()); + break; + } + } + + Ok(summary) + } + + /// Runs one tool call, asked for in the given step of the turn. `None` + /// means the operator stopped the turn while it was running. + async fn run_tool( + &self, + mcp: &McpSession, + call: &ToolCall, + step: usize, + stop: &Notify, + emit: &Emit, + ) -> HostResult> { + let sql = call + .arguments + .get("sql") + .and_then(Value::as_str) + .map(str::to_string); + emit(AgentEvent::ToolCallStarted { + id: call.id.clone(), + tool: call.name.clone(), + arguments: Value::Object(call.arguments.clone()), + sql, + agent: None, + step, + }); + + let started = Instant::now(); + let result = tokio::select! { + result = mcp.call(&call.name, call.arguments.clone()) => Some(result), + () = stop.notified() => None, + }; + let elapsed_ms = u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX); + + let Some(result) = result else { + emit(AgentEvent::ToolCallFinished { + id: call.id.clone(), + is_error: true, + text: "Stopped. The engine cannot cancel a statement, so it may still complete." + .to_string(), + table: None, + engine_notes: Vec::new(), + elapsed_ms, + }); + return Ok(None); + }; + let result = result?; + + emit(AgentEvent::ToolCallFinished { + id: call.id.clone(), + is_error: result.is_error, + text: truncate(&result.text, MAX_UI_TEXT_CHARS), + table: result.structured.as_ref().and_then(table_from_structured), + engine_notes: result.engine_notes.clone(), + elapsed_ms, + }); + + Ok(Some(ToolOutcome { + call_id: call.id.clone(), + name: call.name.clone(), + content: content_for_model(&result), + is_error: result.is_error, + })) + } +} + +/// Tells everything that is waiting on a turn to stop. Several tool calls +/// can be waiting at once, and something may start waiting a moment later, +/// so this wakes those that wait now and leaves word for the next. +fn signal_stop(stop: &Notify) { + stop.notify_waiters(); + stop.notify_one(); +} + +/// Whether a call may run at the same time as others. +/// +/// The engine says so, tool by tool, in the `destructiveHint` it publishes: +/// its query and discovery tools declare that they make no destructive +/// change, and its mutation and lifecycle tools declare that they can. The +/// host goes by that and reads nothing into the statement. A tool that does +/// not say, or one the server does not have, runs alone. +fn runs_with_others(tools: &[ToolSpec], name: &str) -> bool { + tools + .iter() + .find(|tool| tool.name == name) + .is_some_and(|tool| tool.destructive == Some(false)) +} + +/// Splits the calls of one reply into groups, kept in the model's order. +/// The calls of a group run together. Groups run one after another. +/// +/// Neighbouring calls that may run with others share a group. Any other +/// call is a group of its own, so what comes after a change sees the change +/// and what comes before it does not. +fn groups(calls: &[ToolCall], together: impl Fn(&ToolCall) -> bool) -> Vec<&[ToolCall]> { + let mut out = Vec::new(); + let mut start = 0; + for (index, call) in calls.iter().enumerate() { + if !together(call) { + if start < index { + out.push(&calls[start..index]); + } + out.push(&calls[index..=index]); + start = index + 1; + } + } + if start < calls.len() { + out.push(&calls[start..]); + } + out +} + +fn stopped_message() -> Message { + Message::Assistant { + text: "[The operator stopped this turn.]".to_string(), + tool_calls: Vec::new(), + raw: None, + } +} + +/// The tool result as the model receives it: the server's rendering, cut if +/// it is very long. Nothing is added to it. +/// +/// How a result is to be read is the engine's to say, an error or an empty +/// result included. Its MCP server returns a provider call that fails as a +/// tool error, returns a lookup that finds nothing as an empty result, and +/// tells the model how to treat each in the guidance it sends. A note from +/// this app on top of that would be a second opinion on the engine's own +/// answer. +pub fn content_for_model(result: &ToolResult) -> String { + let mut text = if result.text.trim().is_empty() { + result + .structured + .as_ref() + .map_or_else(|| "(no output)".to_string(), Value::to_string) + } else { + result.text.clone() + }; + let length = text.chars().count(); + if length > MAX_MODEL_CHARS { + text = text.chars().take(MAX_MODEL_CHARS).collect(); + text.push_str(&format!( + "\n\n[Output cut: {} more characters. Narrow the query or select fewer columns.]", + length - MAX_MODEL_CHARS + )); + } + text +} + +/// Turns `{ "rows": [ { column: value } ] }` into a table for the grid. +/// Returns `None` for payloads that are not row results. +pub fn table_from_structured(value: &Value) -> Option
{ + let rows = value.get("rows")?.as_array()?; + let mut columns: Vec = Vec::new(); + for row in rows { + for key in row.as_object()?.keys() { + if !columns.contains(key) { + columns.push(key.clone()); + } + } + } + let cells = rows + .iter() + .take(MAX_UI_ROWS) + .map(|row| { + columns + .iter() + .map(|column| match row.get(column) { + None | Some(Value::Null) => None, + Some(Value::String(text)) => Some(text.clone()), + Some(other) => Some(other.to_string()), + }) + .collect() + }) + .collect(); + Some(Table { + columns, + rows: cells, + total_rows: rows.len(), + truncated: rows.len() > MAX_UI_ROWS, + }) +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + + fn result(text: &str, structured: Option, notes: &[&str]) -> ToolResult { + ToolResult { + text: text.to_string(), + structured, + is_error: false, + engine_notes: notes.iter().map(|n| (*n).to_string()).collect(), + } + } + + #[test] + fn the_system_prompt_ends_with_the_engines_guidance_untouched() { + let prompt = system_prompt("# Overview\n\nStackQL exposes providers as SQL."); + assert!(prompt.starts_with("You are the assistant inside StackQL Workbench")); + assert!(prompt.ends_with("# Overview\n\nStackQL exposes providers as SQL.")); + // How the work is shown comes before the engine's words, not after. + let shown = prompt.find("How your work is shown").unwrap(); + let engine = prompt.find(ENGINE_GUIDANCE_INTRO).unwrap(); + assert!(shown < engine); + assert!(prompt.contains("```chart")); + } + + #[test] + fn row_results_become_a_table() { + let table = table_from_structured(&json!({ + "rows": [ + { "name": "wget", "license": "GPL-3.0-or-later", "revision": 2 }, + { "name": "jq", "license": null, "deprecated": false } + ] + })) + .unwrap(); + assert_eq!( + table.columns, + vec!["license", "name", "revision", "deprecated"] + ); + assert_eq!( + table.rows[0], + vec![ + Some("GPL-3.0-or-later".to_string()), + Some("wget".to_string()), + Some("2".to_string()), + None + ] + ); + assert_eq!( + table.rows[1], + vec![ + None, + Some("jq".to_string()), + None, + Some("false".to_string()) + ] + ); + assert_eq!(table.total_rows, 2); + assert!(!table.truncated); + } + + #[test] + fn nested_values_are_kept_as_json_text() { + let table = table_from_structured(&json!({ "rows": [{ "tags": ["a", "b"] }] })).unwrap(); + assert_eq!(table.rows[0], vec![Some("[\"a\",\"b\"]".to_string())]); + } + + #[test] + fn an_empty_row_result_is_an_empty_table() { + let table = table_from_structured(&json!({ "rows": [] })).unwrap(); + assert!(table.columns.is_empty()); + assert!(table.rows.is_empty()); + } + + #[test] + fn other_payloads_are_not_tables() { + assert_eq!(table_from_structured(&json!({ "valid": true })), None); + assert_eq!(table_from_structured(&json!({ "messages": ["ok"] })), None); + assert_eq!(table_from_structured(&json!({ "rows": "nope" })), None); + assert_eq!(table_from_structured(&json!({ "rows": [1, 2] })), None); + } + + #[test] + fn large_row_results_are_capped_for_the_webview() { + let rows: Vec = (0..MAX_UI_ROWS + 10).map(|i| json!({ "n": i })).collect(); + let table = table_from_structured(&json!({ "rows": rows })).unwrap(); + assert_eq!(table.rows.len(), MAX_UI_ROWS); + assert_eq!(table.total_rows, MAX_UI_ROWS + 10); + assert!(table.truncated); + } + + #[test] + fn the_model_gets_the_server_rendering() { + let text = content_for_model(&result("| name |\n|---|\n| wget |", None, &[])); + assert_eq!(text, "| name |\n|---|\n| wget |"); + } + + #[test] + fn the_model_is_told_what_the_engine_said_and_nothing_more() { + // What a provider answered is shown to the operator. It is not added + // to what the model receives: the engine has already decided what + // the model is told about this result. + let text = content_for_model(&result( + "**no results**", + Some(json!({ "rows": [] })), + &["http response status code: 404, response body: Not Found"], + )); + assert_eq!(text, "**no results**"); + } + + #[test] + fn very_long_output_is_cut_for_the_model() { + let long = "x".repeat(MAX_MODEL_CHARS + 500); + let text = content_for_model(&result(&long, None, &[])); + assert!(text.contains("[Output cut: 500 more characters.")); + assert!(text.chars().count() < MAX_MODEL_CHARS + 200); + } + + #[test] + fn a_result_with_no_text_falls_back_to_the_payload() { + let text = content_for_model(&result("", Some(json!({ "valid": true })), &[])); + assert_eq!(text, "{\"valid\":true}"); + assert_eq!(content_for_model(&result(" ", None, &[])), "(no output)"); + } + + fn call(id: &str, name: &str) -> ToolCall { + ToolCall { + id: id.into(), + name: name.into(), + arguments: serde_json::Map::new(), + } + } + + fn tool(name: &str, destructive: Option) -> ToolSpec { + ToolSpec { + name: name.into(), + description: String::new(), + input_schema: json!({ "type": "object" }), + destructive, + } + } + + /// The ids in each group, for a reply whose calls are `(id, tool)`. + fn grouped(calls: &[(&str, &str)]) -> Vec> { + let tools = [ + tool("run_select_query", Some(false)), + tool("list_providers", Some(false)), + tool("run_mutation_query", Some(true)), + tool("says_nothing", None), + ]; + let calls: Vec = calls.iter().map(|(id, name)| call(id, name)).collect(); + groups(&calls, |c| runs_with_others(&tools, &c.name)) + .into_iter() + .map(|group| group.iter().map(|c| c.id.clone()).collect()) + .collect() + } + + #[test] + fn only_tools_the_engine_calls_not_destructive_run_with_others() { + let tools = [ + tool("run_select_query", Some(false)), + tool("run_mutation_query", Some(true)), + tool("says_nothing", None), + ]; + assert!(runs_with_others(&tools, "run_select_query")); + assert!(!runs_with_others(&tools, "run_mutation_query")); + // No word from the engine is not permission. + assert!(!runs_with_others(&tools, "says_nothing")); + // Nor is a tool the server does not have. + assert!(!runs_with_others(&tools, "made_up_by_the_model")); + } + + #[test] + fn independent_queries_share_one_group() { + assert_eq!( + grouped(&[ + ("a", "run_select_query"), + ("b", "list_providers"), + ("c", "run_select_query"), + ]), + [["a", "b", "c"]] + ); + } + + #[test] + fn a_change_runs_alone_and_keeps_its_place() { + assert_eq!( + grouped(&[ + ("a", "run_select_query"), + ("b", "run_select_query"), + ("c", "run_mutation_query"), + ("d", "run_select_query"), + ("e", "run_select_query"), + ]), + [vec!["a", "b"], vec!["c"], vec!["d", "e"]] + ); + // Two changes in a row do not run together either. + assert_eq!( + grouped(&[("a", "run_mutation_query"), ("b", "run_mutation_query")]), + [["a"], ["b"]] + ); + assert_eq!( + grouped(&[("a", "says_nothing"), ("b", "run_select_query")]), + [["a"], ["b"]] + ); + } + + #[test] + fn every_call_lands_in_exactly_one_group_in_order() { + let reply = [ + ("a", "run_mutation_query"), + ("b", "run_select_query"), + ("c", "made_up_by_the_model"), + ("d", "list_providers"), + ("e", "run_select_query"), + ("f", "run_mutation_query"), + ]; + let flat: Vec = grouped(&reply).into_iter().flatten().collect(); + assert_eq!(flat, ["a", "b", "c", "d", "e", "f"]); + assert!(grouped(&[]).is_empty()); + } + + #[tokio::test] + async fn a_stop_reaches_everything_that_is_waiting_and_what_waits_next() { + let stop = Arc::new(Notify::new()); + let waiters: Vec<_> = (0..3) + .map(|_| { + let stop = stop.clone(); + tokio::spawn(async move { stop.notified().await }) + }) + .collect(); + // Let the three start waiting. + tokio::task::yield_now().await; + tokio::time::sleep(std::time::Duration::from_millis(20)).await; + + signal_stop(&stop); + for waiter in waiters { + tokio::time::timeout(std::time::Duration::from_secs(2), waiter) + .await + .expect("a waiter was not woken") + .unwrap(); + } + // Something that starts waiting after the stop still hears of it. + tokio::time::timeout(std::time::Duration::from_secs(2), stop.notified()) + .await + .expect("a late waiter was not told"); + } + + #[test] + fn events_serialise_in_the_shape_the_webview_expects() { + let event = AgentEvent::ToolCallStarted { + id: "c1".into(), + tool: "run_select_query".into(), + arguments: json!({ "sql": "SELECT 1" }), + sql: Some("SELECT 1".into()), + agent: None, + step: 2, + }; + assert_eq!( + serde_json::to_value(&event).unwrap(), + json!({ + "event": "toolCallStarted", + "data": { + "id": "c1", + "tool": "run_select_query", + "arguments": { "sql": "SELECT 1" }, + "sql": "SELECT 1", + "step": 2 + } + }) + ); + let event = AgentEvent::SessionStarted { + mode: SafetyMode::DeleteSafe, + protocol_version: "2025-11-25".into(), + tools: 15, + }; + assert_eq!( + serde_json::to_value(&event).unwrap(), + json!({ + "event": "sessionStarted", + "data": { "mode": "delete_safe", "protocolVersion": "2025-11-25", "tools": 15 } + }) + ); + let event = AgentEvent::DelegateStarted { + mode: SafetyMode::Safe, + agent: "GitHub Copilot CLI".into(), + version: "1.0.113".into(), + protocol: "ACP 1".into(), + model: Some("claude-sonnet-5.5".into()), + tools: 15, + }; + assert_eq!( + serde_json::to_value(&event).unwrap(), + json!({ + "event": "delegateStarted", + "data": { + "mode": "safe", + "agent": "GitHub Copilot CLI", + "version": "1.0.113", + "protocol": "ACP 1", + "model": "claude-sonnet-5.5", + "tools": 15 + } + }) + ); + let event = AgentEvent::AssistantDelta { + id: "m1".into(), + text: "Let me ".into(), + }; + assert_eq!( + serde_json::to_value(&event).unwrap(), + json!({ "event": "assistantDelta", "data": { "id": "m1", "text": "Let me " } }) + ); + } +} diff --git a/src-tauri/src/agent/turnlog.rs b/src-tauri/src/agent/turnlog.rs new file mode 100644 index 0000000..53755f9 --- /dev/null +++ b/src-tauri/src/agent/turnlog.rs @@ -0,0 +1,316 @@ +//! What goes wrong in a turn, written to the app's log. +//! +//! A tool call that fails is part of how a model works: it reads the error, +//! corrects the statement and runs it again. The conversation does not list +//! those attempts. They are written here, with the statement and what came +//! back, so that they can be read when someone needs them. +//! +//! This watches the events of a turn on their way to the webview. It changes +//! none of them, and it makes no judgement of its own: a call is logged as +//! failed when the engine, or the agent, said it failed. + +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; + +use serde_json::{Value, json}; + +use super::runtime::{AgentEvent, TurnSummary}; +use crate::applog::AppLog; +use crate::connection::SafetyMode; +use crate::error::HostResult; +use crate::util::lock; + +/// A tool call that has started and not yet ended. +struct OpenCall { + tool: String, + sql: Option, + arguments: Value, + agent: Option, +} + +pub struct TurnLog { + log: Arc, + /// The backend the turn runs on, as settings name it. + backend: String, + model: String, + mode: SafetyMode, + open: Mutex>, +} + +impl TurnLog { + pub fn new(log: Arc, backend: &str, model: &str, mode: SafetyMode) -> Self { + Self { + log, + backend: backend.to_string(), + model: model.to_string(), + mode, + open: Mutex::new(HashMap::new()), + } + } + + /// Takes note of one event of the turn. + pub fn observe(&self, event: &AgentEvent) { + match event { + AgentEvent::ToolCallStarted { + id, + tool, + arguments, + sql, + agent, + .. + } => { + lock(&self.open).insert( + id.clone(), + OpenCall { + tool: tool.clone(), + sql: sql.clone(), + arguments: arguments.clone(), + agent: agent.clone(), + }, + ); + } + AgentEvent::ToolCallFinished { + id, + is_error, + text, + elapsed_ms, + .. + } => { + let call = lock(&self.open).remove(id); + if !*is_error { + return; + } + let (tool, sql, arguments, agent) = match call { + Some(call) => (Some(call.tool), call.sql, Some(call.arguments), call.agent), + None => (None, None, None, None), + }; + self.log.error( + "tool_call_failed", + json!({ + "backend": self.backend, + "model": self.model, + "mode": self.mode.as_str(), + "tool": tool, + "subagent": agent, + // The statement says it all when there is one. + "sql": sql, + "arguments": if sql.is_some() { None } else { arguments }, + "error": text, + "elapsedMs": elapsed_ms, + }), + ); + } + AgentEvent::Notice { message } => { + self.log.warn( + "notice", + json!({ "backend": self.backend, "message": message }), + ); + } + _ => {} + } + } + + /// The turn ended. A turn that failed is logged with the reason. One + /// that ended in the ordinary way is logged with its size, so that the + /// failures beside it can be placed. + pub fn finished(&self, outcome: &HostResult) { + match outcome { + Ok(summary) => self.log.info( + "turn_finished", + json!({ + "backend": self.backend, + "model": self.model, + "mode": self.mode.as_str(), + "steps": summary.steps, + "toolCalls": summary.tool_calls, + "stopped": summary.stopped, + "stop": summary.stop, + // What the turn used, where the provider said. A count + // it did not report is left out, not written as zero. + "inputTokens": summary.usage.input_tokens, + "outputTokens": summary.usage.output_tokens, + "cachedInputTokens": summary.usage.cached_input_tokens, + }), + ), + Err(err) => self.log.error( + "turn_failed", + json!({ + "backend": self.backend, + "model": self.model, + "mode": self.mode.as_str(), + "kind": err.kind(), + "error": err.to_string(), + }), + ), + } + } +} + +#[cfg(test)] +mod tests { + use std::path::{Path, PathBuf}; + + use super::super::backend::{StopReason, Usage}; + use super::*; + use crate::error::HostError; + + fn temp_dir(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("wb-turnlog-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + dir + } + + /// The records of a log, without the one written when it starts. + fn records(path: &Path) -> Vec { + std::fs::read_to_string(path) + .unwrap() + .lines() + .map(|line| serde_json::from_str::(line).unwrap()) + .filter(|record| record["event"] != "app_started") + .collect() + } + + fn started(id: &str, tool: &str, arguments: Value) -> AgentEvent { + AgentEvent::ToolCallStarted { + id: id.into(), + tool: tool.into(), + sql: arguments + .get("sql") + .and_then(Value::as_str) + .map(str::to_string), + arguments, + agent: None, + step: 1, + } + } + + fn finished(id: &str, is_error: bool, text: &str) -> AgentEvent { + AgentEvent::ToolCallFinished { + id: id.into(), + is_error, + text: text.into(), + table: None, + engine_notes: Vec::new(), + elapsed_ms: 17, + } + } + + #[test] + fn a_failed_call_is_logged_with_its_statement_and_what_came_back() { + let dir = temp_dir("failed"); + let log = Arc::new(AppLog::start(&dir)); + let turn = TurnLog::new( + log.clone(), + "github_copilot", + "small", + SafetyMode::DeleteSafe, + ); + + turn.observe(&started( + "c1", + "run_select_query", + json!({ "sql": "SELEC 1" }), + )); + turn.observe(&started( + "c2", + "run_select_query", + json!({ "sql": "SELECT 1" }), + )); + turn.observe(&finished("c1", true, "syntax error at position 1")); + turn.observe(&finished("c2", false, "| 1 |")); + + let written = records(log.path().unwrap()); + assert_eq!(written.len(), 1, "a call that worked is not logged"); + let record = &written[0]; + assert_eq!(record["event"], "tool_call_failed"); + assert_eq!(record["level"], "error"); + assert_eq!(record["tool"], "run_select_query"); + assert_eq!(record["sql"], "SELEC 1"); + assert_eq!(record["error"], "syntax error at position 1"); + assert_eq!(record["elapsedMs"], 17); + assert_eq!(record["backend"], "github_copilot"); + assert_eq!(record["model"], "small"); + assert_eq!(record["mode"], "delete_safe"); + // The statement is there once, not again inside the arguments. + assert!(record.get("arguments").is_none()); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn a_call_with_no_statement_is_logged_with_its_arguments() { + let dir = temp_dir("arguments"); + let log = Arc::new(AppLog::start(&dir)); + let turn = TurnLog::new(log.clone(), "gemini", "", SafetyMode::Safe); + turn.observe(&AgentEvent::ToolCallStarted { + id: "c1".into(), + tool: "list_services".into(), + arguments: json!({ "provider": "nope" }), + sql: None, + agent: Some("github-count".into()), + step: 1, + }); + turn.observe(&finished("c1", true, "no such provider")); + // A result for a call that was never announced is still logged. + turn.observe(&finished("c9", true, "who knows")); + + let written = records(log.path().unwrap()); + assert_eq!(written.len(), 2); + assert_eq!(written[0]["arguments"], json!({ "provider": "nope" })); + assert_eq!(written[0]["subagent"], "github-count"); + assert!(written[0].get("sql").is_none()); + assert_eq!(written[1]["error"], "who knows"); + assert!(written[1].get("tool").is_none()); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn notices_and_the_end_of_the_turn_are_logged() { + let dir = temp_dir("end"); + let log = Arc::new(AppLog::start(&dir)); + let turn = TurnLog::new( + log.clone(), + "anthropic", + "claude-opus-5-5", + SafetyMode::Safe, + ); + turn.observe(&AgentEvent::Notice { + message: "Stopped after 40 steps without a final answer.".into(), + }); + // Text and the start of a session are not this log's business. + turn.observe(&AgentEvent::AssistantText { + text: "Here is the answer.".into(), + }); + turn.finished(&Ok(TurnSummary { + steps: 3, + tool_calls: 2, + stopped: false, + stop: StopReason::EndTurn, + usage: Usage { + input_tokens: Some(19_353), + output_tokens: Some(92), + cached_input_tokens: None, + }, + })); + turn.finished(&Err(HostError::Agent("The API key was rejected.".into()))); + + let written = records(log.path().unwrap()); + assert_eq!( + written + .iter() + .map(|record| record["event"].as_str().unwrap()) + .collect::>(), + ["notice", "turn_finished", "turn_failed"] + ); + assert_eq!(written[0]["level"], "warn"); + assert_eq!(written[1]["toolCalls"], 2); + assert_eq!(written[1]["stop"]["kind"], "endTurn"); + // What the turn used is on record. What was not reported is absent. + assert_eq!(written[1]["inputTokens"], 19_353); + assert_eq!(written[1]["outputTokens"], 92); + assert!(written[1].get("cachedInputTokens").is_none()); + assert_eq!(written[2]["level"], "error"); + assert_eq!(written[2]["kind"], "agent"); + assert_eq!(written[2]["error"], "The API key was rejected."); + let _ = std::fs::remove_dir_all(dir); + } +} diff --git a/src-tauri/src/applog.rs b/src-tauri/src/applog.rs new file mode 100644 index 0000000..077080c --- /dev/null +++ b/src-tauri/src/applog.rs @@ -0,0 +1,426 @@ +//! The app's own log. +//! +//! One file for each run of the app, named `stackql_workbench_.log`, +//! with one JSON object on each line. It holds what the operator does not +//! need in front of them: a tool call that failed and that the model went on +//! to correct, a turn that could not start, an engine that did not come up. +//! +//! The engine's MCP server keeps its own audit log. That is a different +//! record, written by the engine, in a different folder. This one is written +//! by the host and nothing reads it back. +//! +//! Nothing secret is written here. A record holds statements, tool arguments +//! and what the engine or a provider answered. It never holds an API key, an +//! environment value or what the operator typed to the assistant. + +use std::io::Write; +use std::path::{Path, PathBuf}; +use std::sync::Mutex; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde_json::Value; + +use crate::util::{lock, truncate}; + +const FILE_PREFIX: &str = "stackql_workbench_"; +const FILE_EXTENSION: &str = "log"; +/// Log files beyond this many are removed when the app starts, oldest first. +const MAX_LOG_FILES: usize = 20; +/// Nothing more is written to a file that has reached this size. +const MAX_LOG_BYTES: u64 = 16 * 1024 * 1024; +/// Text in one field beyond this is cut. A provider can answer with a page. +const MAX_FIELD_CHARS: usize = 16_000; +/// What every record starts with. A field cannot take one of these names. +const RESERVED: [&str; 3] = ["timestamp", "level", "event"]; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Level { + Info, + Warn, + Error, +} + +impl Level { + fn as_str(self) -> &'static str { + match self { + Self::Info => "info", + Self::Warn => "warn", + Self::Error => "error", + } + } +} + +pub struct AppLog { + /// `None` records nothing, for tests and for a folder that cannot be made. + path: Option, + write: Mutex<()>, +} + +impl AppLog { + /// Starts the log for this run in `dir`, and removes the oldest files + /// when there are too many. A folder that cannot be created gives a log + /// that records nothing: logging never stops the app. + pub fn start(dir: &Path) -> Self { + Self::start_at(dir, SystemTime::now()) + } + + fn start_at(dir: &Path, now: SystemTime) -> Self { + if std::fs::create_dir_all(dir).is_err() { + return Self::disabled(); + } + prune(dir, MAX_LOG_FILES.saturating_sub(1)); + let log = Self { + path: Some(dir.join(file_name(now))), + write: Mutex::new(()), + }; + log.info( + "app_started", + serde_json::json!({ + "version": env!("CARGO_PKG_VERSION"), + "os": std::env::consts::OS, + "arch": std::env::consts::ARCH, + }), + ); + log + } + + /// A log that records nothing. + pub fn disabled() -> Self { + Self { + path: None, + write: Mutex::new(()), + } + } + + /// The file this run writes to. + pub fn path(&self) -> Option<&Path> { + self.path.as_deref() + } + + pub fn info(&self, event: &str, fields: Value) { + self.record(Level::Info, event, fields); + } + + pub fn warn(&self, event: &str, fields: Value) { + self.record(Level::Warn, event, fields); + } + + pub fn error(&self, event: &str, fields: Value) { + self.record(Level::Error, event, fields); + } + + /// Appends one record. `fields` is an object whose members are written + /// beside the time, the level and the event. A failure to write is + /// ignored, because the log is never the reason something fails. + pub fn record(&self, level: Level, event: &str, fields: Value) { + let Some(path) = &self.path else { return }; + let line = record_line(SystemTime::now(), level, event, fields); + let _guard = lock(&self.write); + if std::fs::metadata(path).is_ok_and(|meta| meta.len() >= MAX_LOG_BYTES) { + return; + } + if let Ok(mut file) = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(path) + { + let _ = writeln!(file, "{line}"); + } + } +} + +/// One record as a line of JSON. The time, the level and the event come +/// first and cannot be replaced by a field of the same name. +/// +/// The line is put together by hand so that those three lead it, which is +/// what someone reading the file looks for. The fields follow in the order +/// of their names. +fn record_line(now: SystemTime, level: Level, event: &str, fields: Value) -> String { + let text = |value: &str| Value::String(value.to_string()).to_string(); + let mut line = format!( + "{{\"timestamp\":{},\"level\":{},\"event\":{}", + text(×tamp(now)), + text(level.as_str()), + text(event) + ); + if let Value::Object(fields) = fields { + for (key, value) in fields { + if RESERVED.contains(&key.as_str()) || value.is_null() { + continue; + } + line.push(','); + line.push_str(&text(&key)); + line.push(':'); + line.push_str(&shortened(value).to_string()); + } + } + line.push('}'); + line +} + +/// Cuts long text, at any depth, so one record cannot fill the file. +fn shortened(value: Value) -> Value { + match value { + Value::String(text) => Value::String(truncate(&text, MAX_FIELD_CHARS)), + Value::Array(items) => Value::Array(items.into_iter().map(shortened).collect()), + Value::Object(members) => Value::Object( + members + .into_iter() + .map(|(key, member)| (key, shortened(member))) + .collect(), + ), + other => other, + } +} + +/// Removes the oldest log files in `dir` until at most `keep` are left. The +/// names sort by time, so the oldest come first. +fn prune(dir: &Path, keep: usize) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + let mut files: Vec = entries + .flatten() + .map(|entry| entry.path()) + .filter(|path| is_log_file(path)) + .collect(); + files.sort(); + let extra = files.len().saturating_sub(keep); + for file in files.iter().take(extra) { + let _ = std::fs::remove_file(file); + } +} + +fn is_log_file(path: &Path) -> bool { + path.extension().is_some_and(|ext| ext == FILE_EXTENSION) + && path + .file_name() + .and_then(|name| name.to_str()) + .is_some_and(|name| name.starts_with(FILE_PREFIX)) +} + +fn since_epoch(now: SystemTime) -> (u64, u32) { + now.duration_since(UNIX_EPOCH).map_or((0, 0), |elapsed| { + (elapsed.as_secs(), elapsed.subsec_millis()) + }) +} + +/// The date and time in UTC for a count of seconds since the Unix epoch: +/// year, month, day, hour, minute, second. +fn utc(secs: u64) -> (i64, u32, u32, u32, u32, u32) { + let days = i64::try_from(secs / 86_400).unwrap_or(0); + let rest = u32::try_from(secs % 86_400).unwrap_or(0); + // Days to a date in the proleptic Gregorian calendar, by counting from + // 1 March of year 0 so that the leap day is the last day of a year. + let shifted = days + 719_468; + let era = shifted.div_euclid(146_097); + let day_of_era = shifted.rem_euclid(146_097); + let year_of_era = + (day_of_era - day_of_era / 1_460 + day_of_era / 36_524 - day_of_era / 146_096) / 365; + let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100); + let month_index = (5 * day_of_year + 2) / 153; + let day = day_of_year - (153 * month_index + 2) / 5 + 1; + let month = if month_index < 10 { + month_index + 3 + } else { + month_index - 9 + }; + let year = year_of_era + era * 400 + i64::from(month <= 2); + ( + year, + u32::try_from(month).unwrap_or(1), + u32::try_from(day).unwrap_or(1), + rest / 3_600, + rest % 3_600 / 60, + rest % 60, + ) +} + +/// RFC 3339 in UTC with milliseconds, for example `2026-11-19T03:47:15.120Z`. +fn timestamp(now: SystemTime) -> String { + let (secs, millis) = since_epoch(now); + let (year, month, day, hour, minute, second) = utc(secs); + format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}.{millis:03}Z") +} + +/// For example `stackql_workbench_20261119T034715Z.log`. The engine names +/// its audit files the same way, with its own prefix. +fn file_name(now: SystemTime) -> String { + let (secs, _) = since_epoch(now); + let (year, month, day, hour, minute, second) = utc(secs); + format!( + "{FILE_PREFIX}{year:04}{month:02}{day:02}T{hour:02}{minute:02}{second:02}Z.{FILE_EXTENSION}" + ) +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use serde_json::json; + + use super::*; + + fn temp_dir(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("wb-applog-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + dir + } + + fn at(secs: u64) -> SystemTime { + UNIX_EPOCH + Duration::from_secs(secs) + } + + fn lines(path: &Path) -> Vec { + std::fs::read_to_string(path) + .unwrap() + .lines() + .map(|line| serde_json::from_str(line).unwrap()) + .collect() + } + + #[test] + fn dates_are_worked_out_in_utc() { + assert_eq!(utc(0), (1970, 1, 1, 0, 0, 0)); + assert_eq!(utc(1_700_000_000), (2023, 11, 14, 22, 13, 20)); + // A leap day in a century year that is a leap year, and an ordinary one. + assert_eq!(utc(951_782_400), (2000, 2, 29, 0, 0, 0)); + assert_eq!(utc(1_709_164_800), (2024, 2, 29, 0, 0, 0)); + // The last second of a year and the first of the next. + assert_eq!(utc(1_704_067_199), (2023, 12, 31, 23, 59, 59)); + assert_eq!(utc(1_704_067_200), (2024, 1, 1, 0, 0, 0)); + } + + #[test] + fn the_file_is_named_for_the_time_the_app_started() { + assert_eq!( + file_name(at(1_700_000_000)), + "stackql_workbench_20231114T221320Z.log" + ); + assert_eq!( + timestamp(at(1_700_000_000) + Duration::from_millis(7)), + "2023-11-14T22:13:20.007Z" + ); + } + + #[test] + fn a_run_gets_its_own_file_with_one_record_on_each_line() { + let dir = temp_dir("records"); + let log = AppLog::start_at(&dir, at(1_700_000_000)); + let path = log.path().unwrap().to_path_buf(); + assert_eq!( + path.file_name().unwrap().to_str().unwrap(), + "stackql_workbench_20231114T221320Z.log" + ); + log.error( + "tool_call_failed", + json!({ "tool": "run_select_query", "sql": "SELEC 1", "error": "line one\nline two" }), + ); + log.warn("notice", json!({ "message": "something to know" })); + + let records = lines(&path); + assert_eq!(records.len(), 3); + assert_eq!(records[0]["event"], "app_started"); + assert_eq!(records[0]["level"], "info"); + assert_eq!(records[1]["event"], "tool_call_failed"); + assert_eq!(records[1]["level"], "error"); + assert_eq!(records[1]["sql"], "SELEC 1"); + // A message with a line break is still one line of the file. + assert_eq!(records[1]["error"], "line one\nline two"); + assert_eq!(records[2]["level"], "warn"); + let stamp = records[1]["timestamp"].as_str().unwrap(); + assert!(stamp.ends_with('Z') && stamp.len() == 24, "{stamp}"); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn a_field_cannot_replace_the_time_the_level_or_the_event() { + let line = record_line( + at(0), + Level::Info, + "real", + json!({ "event": "forged", "level": "error", "timestamp": "never", "kept": 1, "absent": null }), + ); + // The three lead the line, in that order, and each is there once. + assert!( + line.starts_with( + r#"{"timestamp":"1970-01-01T00:00:00.000Z","level":"info","event":"real","# + ), + "{line}" + ); + assert_eq!(line.matches("\"event\"").count(), 1); + let record: Value = serde_json::from_str(&line).unwrap(); + assert_eq!(record["event"], "real"); + assert_eq!(record["level"], "info"); + assert_eq!(record["timestamp"], "1970-01-01T00:00:00.000Z"); + assert_eq!(record["kept"], 1); + assert!(record.get("absent").is_none()); + } + + #[test] + fn long_text_is_cut_at_any_depth() { + let long = "x".repeat(MAX_FIELD_CHARS + 500); + let line = record_line( + at(0), + Level::Error, + "big", + json!({ "error": long, "arguments": { "sql": long } }), + ); + let record: Value = serde_json::from_str(&line).unwrap(); + assert!(record["error"].as_str().unwrap().chars().count() <= MAX_FIELD_CHARS + 3); + assert!( + record["arguments"]["sql"].as_str().unwrap().chars().count() <= MAX_FIELD_CHARS + 3 + ); + } + + #[test] + fn old_files_are_removed_and_other_files_are_left_alone() { + let dir = temp_dir("prune"); + std::fs::create_dir_all(&dir).unwrap(); + for index in 0..MAX_LOG_FILES + 5 { + let name = file_name(at(1_700_000_000 + index as u64)); + std::fs::write(dir.join(name), "{}\n").unwrap(); + } + std::fs::write(dir.join("notes.txt"), "mine").unwrap(); + std::fs::write(dir.join("stackql_mcp_server_20231114T221320Z.log"), "{}").unwrap(); + + let log = AppLog::start_at(&dir, at(1_800_000_000)); + let mut ours: Vec = std::fs::read_dir(&dir) + .unwrap() + .flatten() + .map(|entry| entry.path()) + .filter(|path| is_log_file(path)) + .map(|path| path.file_name().unwrap().to_string_lossy().into_owned()) + .collect(); + ours.sort(); + assert_eq!(ours.len(), MAX_LOG_FILES); + // The newest are kept, with the one this run started. + assert_eq!( + ours.last().map(String::as_str), + log.path() + .and_then(|path| path.file_name()) + .and_then(|name| name.to_str()) + ); + assert_eq!(ours[0], file_name(at(1_700_000_000 + 6))); + assert!(dir.join("notes.txt").exists()); + assert!(dir.join("stackql_mcp_server_20231114T221320Z.log").exists()); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn a_log_with_nowhere_to_write_records_nothing_and_does_not_fail() { + let log = AppLog::disabled(); + assert!(log.path().is_none()); + log.error("anything", json!({ "a": 1 })); + + // A folder that cannot be made, because a file is in the way. + let dir = temp_dir("blocked"); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join("in-the-way"); + std::fs::write(&file, "x").unwrap(); + let log = AppLog::start(&file.join("logs")); + assert!(log.path().is_none()); + log.info("anything", json!({})); + let _ = std::fs::remove_dir_all(dir); + } +} diff --git a/src-tauri/src/config/mod.rs b/src-tauri/src/config/mod.rs new file mode 100644 index 0000000..2ab1876 --- /dev/null +++ b/src-tauri/src/config/mod.rs @@ -0,0 +1,328 @@ +//! Settings, stored as a JSON file in the app config directory. +//! +//! Secrets never go in this file. API keys and tokens live in the OS +//! keychain. + +use std::path::{Path, PathBuf}; +use std::sync::Mutex; + +use serde::{Deserialize, Serialize}; + +use crate::agent::backend::BackendKind; +use crate::connection::SafetyMode; +use crate::error::{HostError, HostResult}; +use crate::util::lock; + +/// Which model the chat uses. The API key is not here. It is in the OS +/// keychain. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct InferenceSettings { + pub kind: BackendKind, + /// Empty means the backend's default model. + #[serde(default)] + pub model: String, + /// Empty means the backend's default address. + #[serde(default)] + pub base_url: Option, + /// For a delegated agent: where its program is. Empty means search + /// `PATH`. + #[serde(default)] + pub program: Option, + /// For a delegated agent: whether it may split independent lookups + /// across subagents. Off unless the operator turns it on. In testing a + /// model also reached for subagents when it was stuck, which made a + /// turn slower and no better. See `docs/spike-acp.md`. + #[serde(default)] + pub subagents: bool, +} + +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase", default)] +pub struct Settings { + /// Explicit location of the `stackql` binary. Empty means search for it. + pub engine_path: Option, + /// A dotenv file the engine sources at startup, passed with `--env.file`. + /// The app never reads it. + pub env_file: Option, + /// The engine's data folder, passed with `--approot`. Empty means the + /// default: beside the app, or under the app data directory when that + /// cannot be written to. + pub approot: Option, + /// What the agent may do without asking. Passed to the engine, which + /// enforces it. + pub safety_mode: SafetyMode, + /// The inference backend. `None` means chat is not configured, and the + /// chat pane is hidden. + pub inference: Option, +} + +impl Settings { + /// Trims text fields and turns empty ones into `None`. + pub fn normalised(mut self) -> Self { + self.engine_path = clean(self.engine_path); + self.env_file = clean(self.env_file); + self.approot = clean(self.approot); + if let Some(inference) = &mut self.inference { + inference.model = inference.model.trim().to_string(); + inference.base_url = clean(inference.base_url.take()); + inference.program = clean(inference.program.take()); + } + self + } +} + +fn clean(value: Option) -> Option { + value + .map(|v| v.trim().trim_matches('"').trim().to_string()) + .filter(|v| !v.is_empty()) +} + +pub struct SettingsStore { + /// `None` keeps settings in memory only, for tests. + path: Option, + current: Mutex, + load_warning: Option, +} + +impl SettingsStore { + /// Reads the file. A missing file gives defaults. A file that cannot be + /// parsed also gives defaults, with a warning to show the operator, and + /// is left untouched until settings are next saved. + pub fn load(path: PathBuf) -> Self { + let (settings, load_warning) = match std::fs::read_to_string(&path) { + Ok(text) => match serde_json::from_str::(&text) { + Ok(settings) => (settings.normalised(), None), + Err(err) => ( + Settings::default(), + Some(format!( + "The settings file {} could not be read and defaults are in use: {err}", + path.display() + )), + ), + }, + Err(err) if err.kind() == std::io::ErrorKind::NotFound => (Settings::default(), None), + Err(err) => ( + Settings::default(), + Some(format!( + "The settings file {} could not be opened and defaults are in use: {err}", + path.display() + )), + ), + }; + Self { + path: Some(path), + current: Mutex::new(settings), + load_warning, + } + } + + pub fn in_memory(settings: Settings) -> Self { + Self { + path: None, + current: Mutex::new(settings.normalised()), + load_warning: None, + } + } + + pub fn get(&self) -> Settings { + lock(&self.current).clone() + } + + pub fn load_warning(&self) -> Option<&str> { + self.load_warning.as_deref() + } + + /// Saves new settings and returns them as stored. + pub fn replace(&self, settings: Settings) -> HostResult { + let settings = settings.normalised(); + if let Some(path) = &self.path { + write_atomically(path, &settings)?; + } + *lock(&self.current) = settings.clone(); + Ok(settings) + } +} + +fn write_atomically(path: &Path, settings: &Settings) -> HostResult<()> { + let fail = |what: &str, err: &dyn std::fmt::Display| { + HostError::Settings(format!("Could not {what} {}: {err}", path.display())) + }; + if let Some(dir) = path.parent() { + std::fs::create_dir_all(dir).map_err(|e| fail("create the folder for", &e))?; + } + let json = serde_json::to_string_pretty(settings).map_err(|e| fail("encode", &e))?; + // Write beside the target and rename, so a crash cannot leave half a file. + let tmp = path.with_extension("json.tmp"); + std::fs::write(&tmp, json).map_err(|e| fail("write", &e))?; + std::fs::rename(&tmp, path).map_err(|e| fail("save", &e))?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn temp_file(name: &str) -> PathBuf { + let dir = + std::env::temp_dir().join(format!("wb-settings-test-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + dir.join("settings.json") + } + + #[test] + fn a_missing_file_gives_defaults_without_a_warning() { + let store = SettingsStore::load(temp_file("missing")); + assert_eq!(store.get(), Settings::default()); + assert_eq!(store.load_warning(), None); + } + + #[test] + fn settings_round_trip_through_the_file() { + let path = temp_file("roundtrip"); + let store = SettingsStore::load(path.clone()); + store + .replace(Settings { + engine_path: Some("C:\\tools\\stackql.exe".into()), + ..Settings::default() + }) + .unwrap(); + + let reloaded = SettingsStore::load(path.clone()); + assert_eq!( + reloaded.get().engine_path.as_deref(), + Some("C:\\tools\\stackql.exe") + ); + let text = std::fs::read_to_string(&path).unwrap(); + assert!( + text.contains("enginePath"), + "camelCase keys expected: {text}" + ); + let _ = std::fs::remove_dir_all(path.parent().unwrap()); + } + + #[test] + fn blank_values_become_none_and_quotes_are_stripped() { + let store = SettingsStore::in_memory(Settings::default()); + let saved = store + .replace(Settings { + engine_path: Some(" \"C:\\Program Files\\StackQL\\stackql.exe\" ".into()), + env_file: Some(" ".into()), + approot: Some(" D:\\stackql data ".into()), + ..Settings::default() + }) + .unwrap(); + assert_eq!( + saved.engine_path.as_deref(), + Some("C:\\Program Files\\StackQL\\stackql.exe") + ); + assert_eq!(saved.env_file, None); + assert_eq!(saved.approot.as_deref(), Some("D:\\stackql data")); + } + + #[test] + fn the_data_folder_round_trips_and_defaults_to_unset() { + assert_eq!(Settings::default().approot, None); + let path = temp_file("approot"); + let store = SettingsStore::load(path.clone()); + store + .replace(Settings { + approot: Some("D:\\stackql".into()), + ..Settings::default() + }) + .unwrap(); + let reloaded = SettingsStore::load(path.clone()).get(); + assert_eq!(reloaded.approot.as_deref(), Some("D:\\stackql")); + let text = std::fs::read_to_string(&path).unwrap(); + assert!(text.contains("\"approot\""), "{text}"); + let _ = std::fs::remove_dir_all(path.parent().unwrap()); + } + + #[test] + fn a_corrupt_file_gives_defaults_and_a_warning() { + let path = temp_file("corrupt"); + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + std::fs::write(&path, "{ not json").unwrap(); + let store = SettingsStore::load(path.clone()); + assert_eq!(store.get(), Settings::default()); + assert!(store.load_warning().unwrap().contains("could not be read")); + let _ = std::fs::remove_dir_all(path.parent().unwrap()); + } + + #[test] + fn the_safety_mode_defaults_to_safe_and_chat_to_unconfigured() { + let settings = Settings::default(); + assert_eq!(settings.safety_mode, SafetyMode::Safe); + assert_eq!(settings.inference, None); + } + + #[test] + fn inference_settings_round_trip_and_never_hold_a_key() { + let path = temp_file("inference"); + let store = SettingsStore::load(path.clone()); + store + .replace(Settings { + safety_mode: SafetyMode::DeleteSafe, + inference: Some(InferenceSettings { + kind: BackendKind::Gemini, + model: " gemini-test ".into(), + base_url: Some(" ".into()), + program: Some(" ".into()), + subagents: false, + }), + ..Settings::default() + }) + .unwrap(); + + let reloaded = SettingsStore::load(path.clone()).get(); + assert_eq!(reloaded.safety_mode, SafetyMode::DeleteSafe); + let inference = reloaded.inference.unwrap(); + assert_eq!(inference.kind, BackendKind::Gemini); + assert_eq!(inference.model, "gemini-test"); + assert_eq!(inference.base_url, None); + assert_eq!(inference.program, None); + assert!(!inference.subagents); + + let text = std::fs::read_to_string(&path).unwrap(); + assert!(text.contains("\"safetyMode\": \"delete_safe\""), "{text}"); + assert!( + !text.to_lowercase().contains("key"), + "no key belongs in settings: {text}" + ); + let _ = std::fs::remove_dir_all(path.parent().unwrap()); + } + + #[test] + fn subagents_are_off_unless_the_operator_turned_them_on() { + let path = temp_file("subagents"); + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + // Saved before the choice existed. + std::fs::write( + &path, + r#"{ "inference": { "kind": "github_copilot", "model": "" } }"#, + ) + .unwrap(); + let inference = SettingsStore::load(path.clone()).get().inference.unwrap(); + assert!(!inference.subagents); + + std::fs::write( + &path, + r#"{ "inference": { "kind": "github_copilot", "model": "", "subagents": true } }"#, + ) + .unwrap(); + let inference = SettingsStore::load(path.clone()).get().inference.unwrap(); + assert!(inference.subagents); + let _ = std::fs::remove_dir_all(path.parent().unwrap()); + } + + #[test] + fn unknown_and_missing_keys_are_tolerated() { + let path = temp_file("forward"); + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + std::fs::write(&path, r#"{ "futureKey": 1 }"#).unwrap(); + let store = SettingsStore::load(path.clone()); + assert_eq!(store.get(), Settings::default()); + assert_eq!(store.load_warning(), None); + let _ = std::fs::remove_dir_all(path.parent().unwrap()); + } +} diff --git a/src-tauri/src/connection/local.rs b/src-tauri/src/connection/local.rs new file mode 100644 index 0000000..a80b5e4 --- /dev/null +++ b/src-tauri/src/connection/local.rs @@ -0,0 +1,699 @@ +//! A connection to a `stackql` engine running as a child process on this +//! machine. +//! +//! This is the only place that knows the engine is a child process. + +use std::collections::HashMap; +use std::ffi::OsString; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use futures_util::FutureExt; +use futures_util::future::BoxFuture; +use tokio::sync::{Notify, watch}; + +use super::{ + AgentChannel, Connection, DelegateBuilder, EngineState, EngineStatus, EventSink, + McpServerCommand, SafetyMode, +}; +use crate::config::SettingsStore; +use crate::engine::approot::{self, Defaults as ApprootDefaults}; +use crate::engine::discovery::{self, Inputs, Resolved}; +use crate::engine::logbuf::LogBuffer; +use crate::engine::port::pick_free_port; +use crate::engine::supervisor::{ChildSpec, EnvSpec, ManagedChild, StdioMode, Supervisor}; +use crate::error::{HostError, HostResult}; +use crate::query::result::{QueryError, QueryEvent, ResultSet, RunSummary}; +use crate::query::session::{PgSession, StatementEvent}; +use crate::query::split::split_statements; +use crate::util::lock; + +/// How long the engine gets to become ready. It normally takes well under a +/// second. +const READY_TIMEOUT: Duration = Duration::from_secs(15); +const READY_POLL: Duration = Duration::from_millis(50); +/// One connect attempt during the readiness check. Kept short because a +/// refused loopback connect is retried by Windows for about half a second. +const READY_ATTEMPT: Duration = Duration::from_millis(300); +/// How many times the engine is started, each time on a fresh port, when it +/// exits at once. +const START_ATTEMPTS: usize = 3; +const LOG_TAIL_LINES: usize = 40; + +/// What a statement needs from a running engine. +#[derive(Clone)] +struct Endpoint { + port: u16, + stderr: LogBuffer, +} + +/// What the running engine was started with. The agent channel starts its +/// MCP server from the same binary, on the same data folder. +#[derive(Clone)] +struct Launch { + binary: PathBuf, + approot: PathBuf, +} + +/// State shared with the task that watches for the engine exiting. +struct Shared { + status: watch::Sender, + endpoint: Mutex>, + launch: Mutex>, + /// Bumped on every start and stop, so a watcher from an earlier engine + /// cannot overwrite the status of a later one. + generation: AtomicU64, +} + +impl Shared { + fn set_status(&self, status: EngineStatus) { + self.status.send_replace(status); + } +} + +pub struct LocalConnection { + supervisor: Supervisor, + /// Where the engine's data folder goes when settings name none. The + /// folder is the engine's `--approot` and its working directory. + approot_defaults: ApprootDefaults, + /// Where the MCP server writes its audit log. + audit_dir: PathBuf, + settings: Arc, + shared: Arc, + /// Serialises start and stop. Holds the engine process. + lifecycle: tokio::sync::Mutex>, + /// The operator's session. One statement runs on it at a time. + session: tokio::sync::Mutex>, + runs: Mutex>>, +} + +impl LocalConnection { + pub fn new( + approot_defaults: ApprootDefaults, + audit_dir: PathBuf, + settings: Arc, + ) -> HostResult { + let supervisor = Supervisor::new().map_err(|err| HostError::Internal(err.to_string()))?; + let (status, _) = watch::channel(EngineStatus::stopped()); + Ok(Self { + supervisor, + approot_defaults, + audit_dir, + settings, + shared: Arc::new(Shared { + status, + endpoint: Mutex::new(None), + launch: Mutex::new(None), + generation: AtomicU64::new(0), + }), + lifecycle: tokio::sync::Mutex::new(None), + session: tokio::sync::Mutex::new(None), + runs: Mutex::new(HashMap::new()), + }) + } + + fn endpoint(&self) -> HostResult { + lock(&self.shared.endpoint) + .clone() + .ok_or(HostError::EngineNotRunning) + } + + /// Arguments for `stackql srv`. See the engine interface section of + /// CLAUDE.md and `docs/spike-pgwire.md` for the reason behind each one. + fn srv_args(&self, port: u16, approot: &Path, env_file: Option<&str>) -> Vec { + let mut args: Vec = vec![ + "srv".into(), + // The default is 0.0.0.0 and the listener has no authentication. + "--pgsrv.address".into(), + "127.0.0.1".into(), + "--pgsrv.port".into(), + port.to_string().into(), + // The default is the working directory. + "--approot".into(), + approot.as_os_str().to_os_string(), + // Without this an upstream API failure is an empty result with + // the reason only on stderr. With it the reason arrives as a + // notice on the connection that ran the statement. + "--pgsrv.debug.enable".into(), + ]; + if let Some(file) = env_file { + args.push("--env.file".into()); + args.push(file.into()); + } + args + } + + /// Arguments for `stackql mcp`. See `docs/spike-mcp.md`. + fn mcp_args(&self, mode: SafetyMode, approot: &Path, env_file: Option<&str>) -> Vec { + let config = serde_json::json!({ + "server": { + "transport": "stdio", + // The engine classifies each statement and enforces this. + "mode": mode.as_str(), + // The default is 30 seconds, which a paged provider query + // can exceed. + "request_timeout": "5m", + "audit": { + "format": "jsonl", + // The default is the working directory. + "file": { "dir": self.audit_dir } + } + } + }); + let mut args: Vec = vec![ + "mcp".into(), + // The default transport is HTTP. + "--mcp.server.type=stdio".into(), + "--approot".into(), + approot.as_os_str().to_os_string(), + ]; + if let Some(file) = env_file { + args.push("--env.file".into()); + args.push(file.into()); + } + args.push("--mcp.config".into()); + args.push(config.to_string().into()); + args + } + + /// How the engine's MCP server is started in a safety mode, from the + /// same binary and on the same data folder as the running engine. + fn mcp_server_command(&self, mode: SafetyMode) -> HostResult { + let launch = lock(&self.shared.launch) + .clone() + .ok_or(HostError::EngineNotRunning)?; + std::fs::create_dir_all(&self.audit_dir).map_err(|err| { + HostError::Agent(format!( + "Could not create the audit folder {}: {err}", + self.audit_dir.display() + )) + })?; + let settings = self.settings.get(); + Ok(McpServerCommand { + args: self.mcp_args(mode, &launch.approot, settings.env_file.as_deref()), + program: launch.binary, + cwd: launch.approot, + }) + } + + /// Starts a supervised child that speaks a protocol over its stdio. + fn piped_child( + &self, + program: PathBuf, + args: Vec, + cwd: PathBuf, + ) -> HostResult { + let spec = ChildSpec { + program, + args, + // Same environment policy as the operator's engine. The model + // never sees any of it: tool results are all it receives. + env: EnvSpec { + inherit: true, + vars: Vec::new(), + }, + cwd, + stdio: StdioMode::Piped, + }; + let mut child = self + .supervisor + .spawn(&spec) + .map_err(|err| HostError::Agent(err.to_string()))?; + let (Some(reader), Some(writer)) = (child.stdout.take(), child.stdin.take()) else { + return Err(HostError::Agent(format!( + "{} started without stdio pipes.", + spec.program.display() + ))); + }; + Ok(AgentChannel { + reader: Box::new(reader), + writer: Box::new(writer), + diagnostics: child.stderr.clone(), + keepalive: Box::new(child), + }) + } + + async fn stop_engine(&self, child: &mut Option) { + self.shared.generation.fetch_add(1, Ordering::SeqCst); + *lock(&self.shared.endpoint) = None; + *lock(&self.shared.launch) = None; + // Drop the session first so its socket closes before the engine goes. + if let Ok(mut session) = self.session.try_lock() { + *session = None; + } + if let Some(mut running) = child.take() { + running.stop().await; + } + } + + async fn start_engine(&self, child: &mut Option) -> EngineStatus { + self.stop_engine(child).await; + let generation = self.shared.generation.load(Ordering::SeqCst); + let settings = self.settings.get(); + + let mut status = EngineStatus { + state: EngineState::Starting, + ..EngineStatus::stopped() + }; + self.shared.set_status(status.clone()); + + let fail = |mut status: EngineStatus, error: String, log_tail: Vec| { + status.state = EngineState::Failed; + status.error = Some(error); + status.log_tail = log_tail; + self.shared.set_status(status.clone()); + status + }; + + // 1. Find the binary. + let inputs = Inputs::from_environment(settings.engine_path.as_ref().map(PathBuf::from)); + let found: Resolved = match discovery::resolve(&inputs, |p| p.is_file()) { + Ok(found) => found, + Err(err) => return fail(status, err.to_string(), Vec::new()), + }; + // Says so when a variable the operator set was passed over. + status.location_source = Some(found.found_via()); + let path = found.path; + status.location = Some(path.display().to_string()); + self.shared.set_status(status.clone()); + + // 2. Check it is stackql and read its version. + match discovery::read_version(&path).await { + Ok(version) => status.version = Some(version.version), + Err(err) => return fail(status, err, Vec::new()), + } + self.shared.set_status(status.clone()); + + // 3. Choose its data folder. A folder named in settings is used or + // reported as unusable. The defaults fall through to one that works. + let chosen = match approot::resolve( + settings.approot.as_deref().map(Path::new), + &self.approot_defaults, + approot::prepare, + ) { + Ok(chosen) => chosen, + Err(err) => return fail(status, err.to_string(), Vec::new()), + }; + status.data_folder = Some(chosen.path.display().to_string()); + status.data_folder_source = Some(chosen.source.label().to_string()); + status.data_folder_note = chosen.note; + self.shared.set_status(status.clone()); + let approot = chosen.path; + + // 4. Start it on a free loopback port, and 5. wait until it answers. + // + // The port is chosen first and given to the engine after, and in + // between something else can take it: another copy of the app, or + // another engine starting at the same moment. The engine then exits + // at once. That is not a reason to give up, so a fresh port is tried + // a few times before the start is called a failure. + let mut attempt = 0; + let (port, running) = loop { + attempt += 1; + let port = match pick_free_port() { + Ok(port) => port, + Err(err) => return fail(status, format!("No free port: {err}"), Vec::new()), + }; + let spec = ChildSpec { + program: path.clone(), + args: self.srv_args(port, &approot, settings.env_file.as_deref()), + // The engine reads provider credentials from its environment. + // Until the keychain store exists, the app's environment is + // the base and an operator-supplied --env.file adds to it. On + // macOS an app started from Finder has a nearly empty + // environment, so the env file is the dependable route there. + env: EnvSpec { + inherit: true, + vars: Vec::new(), + }, + cwd: approot.clone(), + stdio: StdioMode::Detached, + }; + let mut running = match self.supervisor.spawn(&spec) { + Ok(running) => running, + Err(err) => return fail(status, err.to_string(), Vec::new()), + }; + + status.endpoint = Some(format!("127.0.0.1:{port}")); + match wait_ready(port, &running).await { + Ok(reported) => { + if !reported.is_empty() { + status.version = Some(reported); + } + break (port, running); + } + Err(failure) if try_another_port(&failure, attempt) => { + running.stop().await; + } + Err(failure) => { + let tail = running.stderr.tail(LOG_TAIL_LINES); + running.stop().await; + return fail(status, failure.into_reason(), tail); + } + } + }; + + // 6. Publish, and watch for it going away. + *lock(&self.shared.endpoint) = Some(Endpoint { + port, + stderr: running.stderr.clone(), + }); + *lock(&self.shared.launch) = Some(Launch { + binary: path, + approot, + }); + status.state = EngineState::Running; + self.shared.set_status(status.clone()); + + let shared = self.shared.clone(); + let mut exit = running.exit_watch(); + let stderr = running.stderr.clone(); + let running_status = status.clone(); + tokio::spawn(async move { + while exit.borrow().is_none() { + if exit.changed().await.is_err() { + return; + } + } + let info = exit.borrow().clone(); + let Some(info) = info else { return }; + if info.requested || shared.generation.load(Ordering::SeqCst) != generation { + return; + } + *lock(&shared.endpoint) = None; + let code = info + .code + .map_or_else(|| "no exit code".to_string(), |c| format!("exit code {c}")); + shared.set_status(EngineStatus { + state: EngineState::Failed, + error: Some(format!("The engine stopped unexpectedly ({code}).")), + log_tail: stderr.tail(LOG_TAIL_LINES), + endpoint: None, + ..running_status + }); + }); + + *child = Some(running); + status + } +} + +/// Why the engine did not become ready. +#[derive(Debug, Clone, PartialEq, Eq)] +enum NotReady { + /// It exited. The usual reason is that the port chosen for it was taken + /// by something else before the engine could bind it. + Exited(String), + /// It is still there and does not answer. + Silent(String), +} + +impl NotReady { + fn into_reason(self) -> String { + match self { + Self::Exited(reason) | Self::Silent(reason) => reason, + } + } +} + +/// Whether to start the engine again on another port. An engine that exits +/// at once has most likely lost its port to something else, so a fresh port +/// is worth trying, a few times. One that is running and silent would only +/// be silent again. +fn try_another_port(failure: &NotReady, attempt: usize) -> bool { + matches!(failure, NotReady::Exited(_)) && attempt < START_ATTEMPTS +} + +/// Polls until the engine answers `SHOW VERSION`, the engine exits, or time +/// runs out. Returns the version the engine reports. +async fn wait_ready(port: u16, child: &ManagedChild) -> Result { + let deadline = Instant::now() + READY_TIMEOUT; + loop { + if let Some(exit) = child.exit_info() { + let code = exit + .code + .map_or_else(|| "no exit code".to_string(), |c| format!("exit code {c}")); + return Err(NotReady::Exited(format!( + "The engine exited while starting ({code})." + ))); + } + let last_error = match PgSession::connect_with_timeout(port, READY_ATTEMPT).await { + Ok(mut session) => match session.fetch("SHOW VERSION").await { + Ok(result) if result.rows.len() == 1 => { + let version = result + .column("version") + .and_then(|i| result.rows[0].get(i).cloned().flatten()) + .unwrap_or_default(); + return Ok(version); + } + Ok(_) => "SHOW VERSION returned an unexpected result.".to_string(), + Err(err) => err.message, + }, + Err(err) => err.message, + }; + if Instant::now() >= deadline { + return Err(NotReady::Silent(format!( + "The engine did not become ready within {} seconds. Last error: {last_error}", + READY_TIMEOUT.as_secs() + ))); + } + tokio::time::sleep(READY_POLL).await; + } +} + +/// Removes a run from the registry when the run ends, however it ends. +struct RunGuard<'a> { + runs: &'a Mutex>>, + id: String, +} + +impl Drop for RunGuard<'_> { + fn drop(&mut self) { + lock(self.runs).remove(&self.id); + } +} + +fn elapsed_ms(since: Instant) -> u64 { + u64::try_from(since.elapsed().as_millis()).unwrap_or(u64::MAX) +} + +impl Connection for LocalConnection { + fn status(&self) -> EngineStatus { + self.shared.status.borrow().clone() + } + + fn watch_status(&self) -> watch::Receiver { + self.shared.status.subscribe() + } + + fn start(&self) -> BoxFuture<'_, EngineStatus> { + async move { + let mut child = self.lifecycle.lock().await; + self.start_engine(&mut child).await + } + .boxed() + } + + fn restart(&self) -> BoxFuture<'_, EngineStatus> { + self.start() + } + + fn shutdown(&self) -> BoxFuture<'_, ()> { + async move { + let mut child = self.lifecycle.lock().await; + self.stop_engine(&mut child).await; + self.shared.set_status(EngineStatus::stopped()); + } + .boxed() + } + + fn run( + &self, + run_id: String, + sql: String, + sink: EventSink, + ) -> BoxFuture<'_, HostResult> { + async move { + let endpoint = self.endpoint()?; + let mut session = self.session.try_lock().map_err(|_| HostError::Busy)?; + + let abandon = Arc::new(Notify::new()); + lock(&self.runs).insert(run_id.clone(), abandon.clone()); + let _guard = RunGuard { + runs: &self.runs, + id: run_id, + }; + + let statements = split_statements(&sql); + let total = statements.len(); + let started = Instant::now(); + let mut summary = RunSummary { + statements: total, + completed: 0, + failed: false, + abandoned: false, + elapsed_ms: 0, + }; + + for (index, statement) in statements.into_iter().enumerate() { + sink(QueryEvent::StatementStarted { + index, + total, + sql: statement.clone(), + }); + let statement_started = Instant::now(); + let log_mark = endpoint.stderr.mark(); + + // Reconnect if there is no session or the last one broke. + if session.as_ref().is_none_or(PgSession::is_closed) { + *session = None; + match PgSession::connect(endpoint.port).await { + Ok(fresh) => *session = Some(fresh), + Err(error) => { + sink(QueryEvent::StatementFailed { + index, + error, + elapsed_ms: elapsed_ms(statement_started), + }); + summary.failed = true; + break; + } + } + } + let Some(active) = session.as_mut() else { + break; + }; + + let mut forward = |event: StatementEvent| { + sink(match event { + StatementEvent::Columns(columns) => QueryEvent::Columns { index, columns }, + StatementEvent::Rows(rows) => QueryEvent::Rows { index, rows }, + StatementEvent::Notice(notice) => QueryEvent::Notice { index, notice }, + }); + }; + let outcome: Option> = tokio::select! { + result = active.run(&statement, &mut forward) => Some(result), + () = abandon.notified() => None, + }; + + let lines = endpoint.stderr.since(log_mark); + if !lines.is_empty() { + sink(QueryEvent::EngineLog { index, lines }); + } + + match outcome { + Some(Ok(row_count)) => { + sink(QueryEvent::StatementFinished { + index, + row_count, + elapsed_ms: elapsed_ms(statement_started), + }); + summary.completed += 1; + } + Some(Err(error)) => { + if error.connection_lost { + *session = None; + } + sink(QueryEvent::StatementFailed { + index, + error, + elapsed_ms: elapsed_ms(statement_started), + }); + summary.failed = true; + break; + } + None => { + // The statement is still running in the engine. All + // the host can do is let go of the connection. + *session = None; + summary.abandoned = true; + break; + } + } + } + + summary.elapsed_ms = elapsed_ms(started); + Ok(summary) + } + .boxed() + } + + fn abandon(&self, run_id: &str) -> bool { + match lock(&self.runs).get(run_id) { + Some(notify) => { + // notify_one keeps a permit if the run is between statements, + // so the next wait sees it. + notify.notify_one(); + true + } + None => false, + } + } + + fn fetch(&self, sql: String) -> BoxFuture<'_, HostResult> { + async move { + let endpoint = self.endpoint()?; + let mut session = PgSession::connect(endpoint.port) + .await + .map_err(|err| HostError::Query(err.message))?; + session + .fetch(&sql) + .await + .map_err(|err| HostError::Query(err.message)) + } + .boxed() + } + + fn open_agent_channel(&self, mode: SafetyMode) -> BoxFuture<'_, HostResult> { + async move { + let server = self.mcp_server_command(mode)?; + // stdout and stdin carry protocol frames and nothing else. + self.piped_child(server.program, server.args, server.cwd) + } + .boxed() + } + + fn open_delegate_channel<'a>( + &'a self, + mode: SafetyMode, + build: DelegateBuilder<'a>, + ) -> BoxFuture<'a, HostResult> { + async move { + let command = build(self.mcp_server_command(mode)?)?; + self.piped_child(command.program, command.args, command.cwd) + } + .boxed() + } + + fn audit_dir(&self) -> Option { + Some(self.audit_dir.clone()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn an_engine_that_exits_at_once_is_started_again_on_a_fresh_port() { + let exited = NotReady::Exited("The engine exited while starting (exit code 0).".into()); + assert!(try_another_port(&exited, 1)); + assert!(try_another_port(&exited, START_ATTEMPTS - 1)); + // Only so many times. After that it is a failure, with its reason. + assert!(!try_another_port(&exited, START_ATTEMPTS)); + assert_eq!( + exited.into_reason(), + "The engine exited while starting (exit code 0)." + ); + } + + #[test] + fn an_engine_that_is_running_and_silent_is_not_started_again() { + // Another port would not make it answer, and it would cost the + // operator another full wait. + let silent = NotReady::Silent("The engine did not become ready.".into()); + assert!(!try_another_port(&silent, 1)); + } +} diff --git a/src-tauri/src/connection/mod.rs b/src-tauri/src/connection/mod.rs new file mode 100644 index 0000000..607dc98 --- /dev/null +++ b/src-tauri/src/connection/mod.rs @@ -0,0 +1,207 @@ +//! The seam between the app and an engine. +//! +//! Everything above this trait talks to "a connection" and must not assume +//! the engine is a child process on this machine. `LocalConnection` is the +//! only implementation for now. A remote connection comes later and must not +//! need changes above this line. + +pub mod local; + +use std::any::Any; +use std::ffi::OsString; +use std::path::PathBuf; + +use futures_util::future::BoxFuture; +use serde::{Deserialize, Serialize}; +use tokio::io::{AsyncRead, AsyncWrite}; +use tokio::sync::watch; + +pub use crate::engine::logbuf::LogBuffer; +use crate::error::HostResult; +use crate::query::result::{QueryEvent, ResultSet, RunSummary}; + +/// The workspace safety setting. It maps directly onto the MCP server's +/// `server.mode`. The engine does the classification and the gating. The +/// host only passes the mode on and renders the approval prompt. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SafetyMode { + ReadOnly, + #[default] + Safe, + DeleteSafe, + FullAccess, +} + +impl SafetyMode { + /// The value the engine expects in `server.mode`. + pub fn as_str(self) -> &'static str { + match self { + Self::ReadOnly => "read_only", + Self::Safe => "safe", + Self::DeleteSafe => "delete_safe", + Self::FullAccess => "full_access", + } + } +} + +/// A byte stream to the engine's MCP server, for the agent runtime only. +/// +/// For a local engine this is the stdio of a child process. For a remote +/// engine it would be something else, which is why the agent runtime gets +/// streams and not a process. +pub struct AgentChannel { + /// Protocol frames from the server. + pub reader: Box, + /// Protocol frames to the server. + pub writer: Box, + /// What the server writes outside the protocol. Upstream failures show + /// up here and nowhere else. + pub diagnostics: LogBuffer, + /// Keeps the channel open. Dropping it tears the channel down. + pub keepalive: Box, +} + +/// How a program that is its own MCP client starts the engine's MCP +/// server, already set to a safety mode. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct McpServerCommand { + pub program: PathBuf, + pub args: Vec, + pub cwd: PathBuf, +} + +/// A program on this machine to run for the agent runtime: an agent the +/// operator installed. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DelegateCommand { + pub program: PathBuf, + pub args: Vec, + pub cwd: PathBuf, +} + +/// Turns the way the engine's MCP server is started into the command line +/// of an agent that will start it. +pub type DelegateBuilder<'a> = + Box HostResult + Send + 'a>; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub enum EngineState { + Stopped, + Starting, + Running, + Failed, +} + +/// What the status bar shows. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct EngineStatus { + pub state: EngineState, + /// Where the engine is. For a local engine, the path of the binary. + pub location: Option, + /// How the location was found, for example "PATH" or "settings". + pub location_source: Option, + pub version: Option, + /// The address statements are sent to. + pub endpoint: Option, + /// Where the engine keeps its provider cache, when that is a folder on + /// this machine. + pub data_folder: Option, + /// How the data folder was chosen, for example "settings". + pub data_folder_source: Option, + /// Set when the data folder is not the one the operator would expect, + /// with the reason. + pub data_folder_note: Option, + /// Why the engine is not running, when it should be. + pub error: Option, + /// The last lines the engine wrote to stderr. Shown with a failure. + pub log_tail: Vec, +} + +impl EngineStatus { + pub fn stopped() -> Self { + Self { + state: EngineState::Stopped, + location: None, + location_source: None, + version: None, + endpoint: None, + data_folder: None, + data_folder_source: None, + data_folder_note: None, + error: None, + log_tail: Vec::new(), + } + } +} + +/// Receives the events of a run as they happen. +pub type EventSink = Box; + +pub trait Connection: Send + Sync + 'static { + /// The current status. + fn status(&self) -> EngineStatus; + + /// A receiver that changes whenever the status does. + fn watch_status(&self) -> watch::Receiver; + + /// Brings the engine up. Returns the resulting status. A failure is + /// reported in the status, not as an error, because it is a state the UI + /// shows and the operator can act on. + fn start(&self) -> BoxFuture<'_, EngineStatus>; + + /// Stops and starts the engine. This is also the only way to stop a + /// statement that is running, since the engine has no cancel. + fn restart(&self) -> BoxFuture<'_, EngineStatus>; + + /// Stops the engine. Called when the app exits. + fn shutdown(&self) -> BoxFuture<'_, ()>; + + /// Runs the statements in `sql` in order on the operator's session, + /// stopping at the first failure. Events go to `sink` as they happen. + /// + /// This is the human channel: the text was written or explicitly run by + /// the operator. + fn run( + &self, + run_id: String, + sql: String, + sink: EventSink, + ) -> BoxFuture<'_, HostResult>; + + /// Stops waiting for a run. Returns false if there is no such run. + /// + /// This does not stop the statement in the engine. See + /// `docs/spike-pgwire.md`. + fn abandon(&self, run_id: &str) -> bool; + + /// Runs one host-built statement on its own short-lived session and + /// returns the whole result. Used for metadata. Never pass text from the + /// webview here. + fn fetch(&self, sql: String) -> BoxFuture<'_, HostResult>; + + /// Opens the agent channel: a fresh MCP server session in the given + /// safety mode. Statements sent here originate from a model, so this is + /// kept apart from the operator's channel on purpose. + fn open_agent_channel(&self, mode: SafetyMode) -> BoxFuture<'_, HostResult>; + + /// Starts an agent the operator installed, which is its own MCP client, + /// and returns the streams of its protocol. `build` is told how the + /// engine's MCP server is started in the given safety mode and answers + /// with the agent's command line. + /// + /// The agent is supervised like any other child. It is still the agent + /// channel: what reaches the engine this way originates from a model, + /// and the engine applies the safety mode to it. + fn open_delegate_channel<'a>( + &'a self, + mode: SafetyMode, + build: DelegateBuilder<'a>, + ) -> BoxFuture<'a, HostResult>; + + /// The directory the engine writes its agent audit log to, if it keeps + /// one where the host can read it. + fn audit_dir(&self) -> Option; +} diff --git a/src-tauri/src/engine/approot.rs b/src-tauri/src/engine/approot.rs new file mode 100644 index 0000000..7f23d89 --- /dev/null +++ b/src-tauri/src/engine/approot.rs @@ -0,0 +1,354 @@ +//! Choosing the engine's data folder, its `--approot`. +//! +//! The engine keeps its provider cache there. Its own default is `.stackql` +//! in the working directory, which for a desktop app is wherever it happened +//! to be started from, so the host always passes the folder explicitly. +//! +//! Resolution order, first hit wins: +//! +//! 1. Explicit folder in settings +//! 2. `.stackql` beside the Workbench executable +//! 3. A folder under the app data directory +//! +//! The explicit source is strict. If the operator named a folder and it +//! cannot be used, that is an error and the search stops there. The second +//! falls through to the third with a note, because an installed app usually +//! sits where an ordinary account cannot write. + +use std::path::{Path, PathBuf}; + +/// The folder name used beside the executable. It is the name the engine +/// uses for its own default. +pub const FOLDER_NAME: &str = ".stackql"; + +/// Where a resolved data folder came from. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Source { + Settings, + BesideApp, + AppData, +} + +impl Source { + /// A short label for the settings pane. + pub fn label(self) -> &'static str { + match self { + Self::Settings => "settings", + Self::BesideApp => "beside the app", + Self::AppData => "app data folder", + } + } +} + +/// The folders tried when settings name none. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Defaults { + /// `.stackql` beside the executable. `None` when there is no such place + /// or it must not be written to. + pub beside_app: Option, + /// A folder under the app data directory, which an ordinary account can + /// always write to. + pub fallback: PathBuf, +} + +impl Defaults { + /// The defaults for an app whose executable is `exe`. + pub fn for_executable(exe: Option<&Path>, fallback: PathBuf) -> Self { + Self { + beside_app: exe.and_then(beside_executable), + fallback, + } + } + + /// One fixed folder and nothing else. Tests use this. + pub fn fixed(dir: PathBuf) -> Self { + Self { + beside_app: None, + fallback: dir, + } + } +} + +/// The data folder beside an executable, if there may be one. +/// +/// There is none inside a macOS app bundle. Adding a file to a signed bundle +/// breaks its signature, and the bundle is replaced whole on update. +pub fn beside_executable(exe: &Path) -> Option { + let dir = exe.parent().filter(|dir| !dir.as_os_str().is_empty())?; + if super::in_app_bundle(exe) { + return None; + } + Some(dir.join(FOLDER_NAME)) +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Resolved { + pub path: PathBuf, + pub source: Source, + /// Set when the folder is not the one the operator would expect, with + /// the reason. + pub note: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum ApprootError { + #[error( + "The engine data folder in settings is not a full path: {0}. Give a full path in Settings, or clear it to use the default folder." + )] + SettingsPathRelative(String), + #[error( + "The engine data folder in settings cannot be used: {path} ({reason}). Correct it in Settings, or clear it to use the default folder." + )] + SettingsPathUnusable { path: String, reason: String }, + #[error( + "The engine data folder {path} cannot be used ({reason}). Set a folder you can write to in Settings." + )] + NoneUsable { path: String, reason: String }, +} + +/// Creates the folder if it is missing and checks a file can be written in +/// it. This is the `prepare` that [`resolve`] is given outside tests. +pub fn prepare(dir: &Path) -> std::io::Result<()> { + std::fs::create_dir_all(dir)?; + let probe = dir.join(format!(".workbench-write-test-{}", std::process::id())); + std::fs::write(&probe, b"")?; + let _ = std::fs::remove_file(&probe); + Ok(()) +} + +/// Runs the search. `prepare` makes a folder ready and says whether it can +/// be used. It is injected so tests can describe a file system. +pub fn resolve( + setting: Option<&Path>, + defaults: &Defaults, + prepare: impl Fn(&Path) -> std::io::Result<()>, +) -> Result { + if let Some(path) = setting { + // A relative path would be read against the directory the app was + // started from, which is the thing an explicit folder is meant to + // avoid. + if !path.is_absolute() { + return Err(ApprootError::SettingsPathRelative( + path.display().to_string(), + )); + } + return match prepare(path) { + Ok(()) => Ok(Resolved { + path: path.to_path_buf(), + source: Source::Settings, + note: None, + }), + Err(err) => Err(ApprootError::SettingsPathUnusable { + path: path.display().to_string(), + reason: err.to_string(), + }), + }; + } + + let mut note = None; + if let Some(path) = &defaults.beside_app { + match prepare(path) { + Ok(()) => { + return Ok(Resolved { + path: path.clone(), + source: Source::BesideApp, + note: None, + }); + } + Err(err) => { + note = Some(format!( + "The folder beside the app, {}, cannot be written to ({err}), so the app data folder is used.", + path.display() + )); + } + } + } + + match prepare(&defaults.fallback) { + Ok(()) => Ok(Resolved { + path: defaults.fallback.clone(), + source: Source::AppData, + note, + }), + Err(err) => Err(ApprootError::NoneUsable { + path: defaults.fallback.display().to_string(), + reason: err.to_string(), + }), + } +} + +#[cfg(test)] +mod tests { + use std::cell::RefCell; + use std::io; + + use super::*; + + fn abs(path: &str) -> PathBuf { + if cfg!(windows) { + PathBuf::from(format!("C:{}", path.replace('/', "\\"))) + } else { + PathBuf::from(path) + } + } + + fn defaults() -> Defaults { + Defaults { + beside_app: Some(abs("/apps/workbench/.stackql")), + fallback: abs("/data/engine"), + } + } + + fn denied() -> io::Error { + io::Error::new(io::ErrorKind::PermissionDenied, "access is denied") + } + + /// A file system in which only the listed folders can be written to. + /// Records what was tried, in order. + fn writable<'a>( + ok: &'a [PathBuf], + tried: &'a RefCell>, + ) -> impl Fn(&Path) -> io::Result<()> + 'a { + move |dir| { + tried.borrow_mut().push(dir.to_path_buf()); + if ok.iter().any(|allowed| allowed == dir) { + Ok(()) + } else { + Err(denied()) + } + } + } + + #[test] + fn the_folder_in_settings_wins_and_nothing_else_is_touched() { + let chosen = abs("/my/approot"); + let ok = [chosen.clone(), abs("/apps/workbench/.stackql")]; + let tried = RefCell::new(Vec::new()); + let found = resolve(Some(&chosen), &defaults(), writable(&ok, &tried)).unwrap(); + assert_eq!(found.path, chosen); + assert_eq!(found.source, Source::Settings); + assert_eq!(found.note, None); + assert_eq!(*tried.borrow(), vec![chosen]); + } + + #[test] + fn an_unusable_folder_in_settings_is_an_error_and_the_search_stops() { + let chosen = abs("/locked/approot"); + let ok = [abs("/apps/workbench/.stackql"), abs("/data/engine")]; + let tried = RefCell::new(Vec::new()); + let err = resolve(Some(&chosen), &defaults(), writable(&ok, &tried)).unwrap_err(); + assert!(matches!(err, ApprootError::SettingsPathUnusable { .. })); + let text = err.to_string(); + assert!(text.contains("Settings"), "points at settings: {text}"); + assert!( + text.contains("access is denied"), + "gives the reason: {text}" + ); + assert_eq!(*tried.borrow(), vec![chosen]); + } + + #[test] + fn a_relative_folder_in_settings_is_an_error() { + let tried = RefCell::new(Vec::new()); + let err = resolve( + Some(Path::new("cache/stackql")), + &defaults(), + writable(&[], &tried), + ) + .unwrap_err(); + assert!(matches!(err, ApprootError::SettingsPathRelative(_))); + assert!(tried.borrow().is_empty(), "nothing may be created"); + } + + #[test] + fn the_folder_beside_the_app_is_the_default() { + let ok = [abs("/apps/workbench/.stackql"), abs("/data/engine")]; + let tried = RefCell::new(Vec::new()); + let found = resolve(None, &defaults(), writable(&ok, &tried)).unwrap(); + assert_eq!(found.path, abs("/apps/workbench/.stackql")); + assert_eq!(found.source, Source::BesideApp); + assert_eq!(found.note, None); + assert_eq!(tried.borrow().len(), 1, "the fallback is not created"); + } + + #[test] + fn a_read_only_install_folder_falls_back_to_app_data_with_a_note() { + let ok = [abs("/data/engine")]; + let tried = RefCell::new(Vec::new()); + let found = resolve(None, &defaults(), writable(&ok, &tried)).unwrap(); + assert_eq!(found.path, abs("/data/engine")); + assert_eq!(found.source, Source::AppData); + let note = found.note.unwrap(); + assert!(note.contains(".stackql"), "names the folder: {note}"); + assert!( + note.contains("access is denied"), + "gives the reason: {note}" + ); + } + + #[test] + fn with_no_folder_beside_the_app_the_fallback_is_used_without_a_note() { + let fixed = Defaults::fixed(abs("/data/engine")); + let ok = [abs("/data/engine")]; + let tried = RefCell::new(Vec::new()); + let found = resolve(None, &fixed, writable(&ok, &tried)).unwrap(); + assert_eq!(found.path, abs("/data/engine")); + assert_eq!(found.source, Source::AppData); + assert_eq!(found.note, None); + } + + #[test] + fn nothing_usable_is_an_error_that_points_at_settings() { + let tried = RefCell::new(Vec::new()); + let err = resolve(None, &defaults(), writable(&[], &tried)).unwrap_err(); + assert!(matches!(err, ApprootError::NoneUsable { .. })); + assert!(err.to_string().contains("Settings")); + assert_eq!(tried.borrow().len(), 2); + } + + #[test] + fn the_default_sits_beside_the_executable() { + let exe = abs("/apps/workbench/stackql-workbench.exe"); + assert_eq!( + beside_executable(&exe), + Some(abs("/apps/workbench/.stackql")) + ); + let made = Defaults::for_executable(Some(&exe), abs("/data/engine")); + assert_eq!(made, defaults()); + } + + #[test] + fn nothing_is_written_inside_a_macos_app_bundle() { + let exe = Path::new("/Applications/StackQL Workbench.app/Contents/MacOS/stackql-workbench"); + assert_eq!(beside_executable(exe), None); + let made = Defaults::for_executable(Some(exe), abs("/data/engine")); + assert_eq!(made, Defaults::fixed(abs("/data/engine"))); + } + + #[test] + fn an_unknown_executable_gives_only_the_fallback() { + assert_eq!(beside_executable(Path::new("stackql-workbench")), None); + let made = Defaults::for_executable(None, abs("/data/engine")); + assert_eq!(made, Defaults::fixed(abs("/data/engine"))); + } + + #[test] + fn prepare_creates_the_folder_and_leaves_nothing_in_it() { + let root = std::env::temp_dir().join(format!("wb-approot-test-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + let dir = root.join("nested").join(FOLDER_NAME); + + prepare(&dir).unwrap(); + assert!(dir.is_dir()); + assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 0); + // A second run on an existing folder is fine too. + prepare(&dir).unwrap(); + + // A file where the folder should be cannot be used. + let file = root.join("a-file"); + std::fs::write(&file, b"x").unwrap(); + assert!(prepare(&file).is_err()); + + let _ = std::fs::remove_dir_all(&root); + } +} diff --git a/src-tauri/src/engine/discovery.rs b/src-tauri/src/engine/discovery.rs new file mode 100644 index 0000000..961d39a --- /dev/null +++ b/src-tauri/src/engine/discovery.rs @@ -0,0 +1,671 @@ +//! Finding the `stackql` binary and reading its version. +//! +//! Resolution order, first hit wins: +//! +//! 1. Explicit path in settings +//! 2. The engine installed with the app: beside the Workbench executable, +//! and on macOS, for an app that runs from a bundle, where the PKG puts +//! the `stackql` command +//! 3. `STACKQL_BIN` environment variable +//! 4. Well-known install locations for the platform +//! 5. `PATH` +//! +//! The installers ship `stackql` with the Workbench, and that pair is the +//! one that was built and tested together. So the engine installed with the +//! app is the default, and the one thing that comes before it is a path the +//! operator set in Settings, which can only happen after the install. An +//! environment variable can be older than the install and would otherwise +//! swap the engine without anyone having chosen that. When the variable is +//! set and passed over, the status says so. +//! +//! The two platforms lay the pair out differently. The MSI puts the two +//! executables in one folder. On macOS the app is a bundle in +//! `/Applications` and the PKG puts the command in `/usr/local/bin`. An +//! engine inside the bundle, beside the executable, is found first if a +//! later PKG puts one there. +//! +//! A build from this repository has no engine beside it and no installer +//! behind it, so there the variable is the next thing tried. +//! +//! The two explicit sources are strict. If the operator named a path and it is +//! not a file, that is reported as an error and the search does not carry on, +//! because quietly running a different binary than the one asked for would be +//! worse than stopping. + +use std::ffi::OsString; +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use serde::Serialize; + +/// File name of the engine binary on this platform. +pub const BINARY_NAME: &str = if cfg!(windows) { + "stackql.exe" +} else { + "stackql" +}; + +/// Where a resolved binary came from. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub enum Source { + Settings, + Sibling, + /// Where the app's own installer puts the engine, when that is not + /// beside the app. + WithApp, + EnvVar, + WellKnown, + Path, +} + +impl Source { + /// A short label for the status bar. + pub fn label(self) -> &'static str { + match self { + Self::Settings => "settings", + Self::Sibling => "beside the app", + Self::WithApp => "installed with the app", + Self::EnvVar => "STACKQL_BIN", + Self::WellKnown => "install location", + Self::Path => "PATH", + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Resolved { + pub path: PathBuf, + pub source: Source, + /// `STACKQL_BIN` is set and was not used, because the engine beside the + /// app comes first. + pub env_passed_over: bool, +} + +impl Resolved { + fn new(path: PathBuf, source: Source) -> Self { + Self { + path, + source, + env_passed_over: false, + } + } + + /// How the binary was found, in a few words for the status bar. It says + /// when a variable the operator set was passed over, so that an engine + /// other than the one they named is never run without a word. + pub fn found_via(&self) -> String { + if self.env_passed_over { + format!( + "{} (STACKQL_BIN is set and not used. To use another engine, set it in Settings)", + self.source.label() + ) + } else { + self.source.label().to_string() + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum DiscoveryError { + #[error( + "The engine path in settings does not point to a file: {0}. Correct it in Settings, or clear it to search for stackql automatically." + )] + SettingsPathInvalid(String), + #[error("STACKQL_BIN does not point to a file: {0}. Correct or unset the variable.")] + EnvPathInvalid(String), + #[error( + "No stackql binary was found. Set its location in Settings, or set STACKQL_BIN, or add stackql to PATH." + )] + NotFound, +} + +/// Everything discovery looks at, gathered up front so the search itself is a +/// pure function and can be tested without touching the machine. +#[derive(Debug, Clone, Default)] +pub struct Inputs { + pub settings_path: Option, + pub env_bin: Option, + pub exe_dir: Option, + /// Where the installer that put this app down also puts the engine, + /// when that is not beside the executable. See [`installed_with_app`]. + pub with_app: Vec, + pub well_known: Vec, + pub path_var: Option, +} + +impl Inputs { + /// Reads the real environment of this process. + pub fn from_environment(settings_path: Option) -> Self { + let exe = std::env::current_exe().ok(); + Self { + settings_path, + env_bin: std::env::var_os("STACKQL_BIN").filter(|v| !v.is_empty()), + exe_dir: exe + .as_deref() + .and_then(|exe| exe.parent().map(Path::to_path_buf)), + with_app: installed_with_app(exe.as_deref(), cfg!(target_os = "macos")), + well_known: well_known_locations(|name| std::env::var_os(name)), + path_var: std::env::var_os("PATH"), + } + } +} + +/// Where the StackQL PKG puts the `stackql` command on macOS. +const MACOS_PKG_DIR: &str = "/usr/local/bin"; + +/// Where the installer that put an installed copy of this app down also +/// puts the engine, when that is not beside the executable. +/// +/// On Windows there is no such place. The MSI puts the two side by side, +/// which the search already covers. +/// +/// On macOS the app is a bundle, and the PKG puts the `stackql` command in +/// `/usr/local/bin` so that a terminal finds it. An app that runs from a +/// bundle takes that one as its own, the same as an engine beside it. A +/// build that is not in a bundle is a build from this repository. It has no +/// installer behind it, and for it that folder is one more place to look. +pub fn installed_with_app(exe: Option<&Path>, macos: bool) -> Vec { + if macos && exe.is_some_and(super::in_app_bundle) { + vec![PathBuf::from(MACOS_PKG_DIR).join(BINARY_NAME)] + } else { + Vec::new() + } +} + +/// Install locations used by the StackQL installers and common package managers. +pub fn well_known_locations(env: impl Fn(&str) -> Option) -> Vec { + let mut out = Vec::new(); + if cfg!(windows) { + for var in ["ProgramFiles", "ProgramW6432", "ProgramFiles(x86)"] { + if let Some(dir) = env(var) { + out.push(PathBuf::from(dir).join("StackQL").join(BINARY_NAME)); + } + } + if let Some(dir) = env("LOCALAPPDATA") { + out.push( + PathBuf::from(dir) + .join("Programs") + .join("StackQL") + .join(BINARY_NAME), + ); + } + out.dedup(); + } else { + // The PKG installer puts the CLI in /usr/local/bin. The others are + // where the common macOS package manager links binaries. + out.push(PathBuf::from(MACOS_PKG_DIR).join(BINARY_NAME)); + out.push(PathBuf::from("/opt/homebrew/bin").join(BINARY_NAME)); + } + out +} + +/// Runs the search. `is_file` is injected so tests can describe a file system. +pub fn resolve( + inputs: &Inputs, + is_file: impl Fn(&Path) -> bool, +) -> Result { + if let Some(path) = &inputs.settings_path { + return if is_file(path) { + Ok(Resolved::new(path.clone(), Source::Settings)) + } else { + Err(DiscoveryError::SettingsPathInvalid( + path.display().to_string(), + )) + }; + } + + // The engine that was installed with the app. It comes before the + // variable, which is not even looked at here: a variable left over from + // before the install, right or wrong, must not stop the pair that + // shipped together from starting. + if let Some(dir) = &inputs.exe_dir { + let path = dir.join(BINARY_NAME); + if is_file(&path) { + return Ok(Resolved { + path, + source: Source::Sibling, + env_passed_over: inputs.env_bin.is_some(), + }); + } + } + // The same, for an installer that puts the engine somewhere other than + // beside the app. An engine beside the app comes first: it is the one + // that cannot have been put there by anything else. + for path in &inputs.with_app { + if is_file(path) { + return Ok(Resolved { + path: path.clone(), + source: Source::WithApp, + env_passed_over: inputs.env_bin.is_some(), + }); + } + } + + if let Some(value) = &inputs.env_bin { + let path = PathBuf::from(value); + return if is_file(&path) { + Ok(Resolved::new(path, Source::EnvVar)) + } else { + Err(DiscoveryError::EnvPathInvalid(path.display().to_string())) + }; + } + + for path in &inputs.well_known { + if is_file(path) { + return Ok(Resolved::new(path.clone(), Source::WellKnown)); + } + } + + if let Some(path_var) = &inputs.path_var { + for dir in std::env::split_paths(path_var) { + if dir.as_os_str().is_empty() { + continue; + } + let path = dir.join(BINARY_NAME); + if is_file(&path) { + return Ok(Resolved::new(path, Source::Path)); + } + } + } + + Err(DiscoveryError::NotFound) +} + +/// What `stackql --version` reports. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct EngineVersion { + pub version: String, + pub platform: Option, + pub commit: Option, +} + +/// Parses the first line of `stackql --version`, for example +/// `stackql v1.0.888 Windows (f7b4116)`. +pub fn parse_version(output: &str) -> Option { + let line = output.lines().find(|l| !l.trim().is_empty())?.trim(); + let mut words = line.split_whitespace(); + if words.next()? != "stackql" { + return None; + } + let version = words.next()?.trim_start_matches('v').to_string(); + if version.is_empty() || !version.starts_with(|c: char| c.is_ascii_digit()) { + return None; + } + let mut platform = None; + let mut commit = None; + for word in words { + if let Some(inner) = word.strip_prefix('(').and_then(|w| w.strip_suffix(')')) { + commit = Some(inner.to_string()); + } else if platform.is_none() { + platform = Some(word.to_string()); + } + } + Some(EngineVersion { + version, + platform, + commit, + }) +} + +/// Asks the binary for its version. Fails if it does not answer in time or +/// the output is not recognised, which also catches a path that is not +/// really `stackql`. +pub async fn read_version(binary: &Path) -> Result { + let mut cmd = tokio::process::Command::new(binary); + cmd.arg("--version") + .stdin(std::process::Stdio::null()) + .kill_on_drop(true); + super::hide_console_window(&mut cmd); + let output = tokio::time::timeout(Duration::from_secs(10), cmd.output()) + .await + .map_err(|_| { + format!( + "{} --version did not answer within 10 seconds.", + binary.display() + ) + })? + .map_err(|err| format!("Could not run {}: {err}", binary.display()))?; + let stdout = String::from_utf8_lossy(&output.stdout); + parse_version(&stdout).ok_or_else(|| { + format!( + "{} does not look like stackql. Its --version output was not recognised.", + binary.display() + ) + }) +} + +#[cfg(test)] +mod tests { + use std::collections::HashSet; + + use super::*; + + fn fs(files: &[&str]) -> impl Fn(&Path) -> bool + use<> { + let set: HashSet = files.iter().map(PathBuf::from).collect(); + move |p: &Path| set.contains(p) + } + + fn path_var(dirs: &[&str]) -> Option { + std::env::join_paths(dirs.iter().map(PathBuf::from)).ok() + } + + fn bin_in(dir: &str) -> String { + PathBuf::from(dir).join(BINARY_NAME).display().to_string() + } + + fn everything() -> (Inputs, Vec) { + let sibling = bin_in("/app"); + let well_known = bin_in("/opt/known"); + let on_path = bin_in("/usr/bin"); + let inputs = Inputs { + settings_path: Some(PathBuf::from("/custom/stackql-custom")), + env_bin: Some(OsString::from("/env/stackql-env")), + exe_dir: Some(PathBuf::from("/app")), + with_app: Vec::new(), + well_known: vec![PathBuf::from(&well_known)], + path_var: path_var(&["/somewhere", "/usr/bin"]), + }; + let files = vec![ + "/custom/stackql-custom".to_string(), + "/env/stackql-env".to_string(), + sibling, + well_known, + on_path, + ]; + (inputs, files) + } + + fn resolve_with(inputs: &Inputs, files: &[String]) -> Result { + let refs: Vec<&str> = files.iter().map(String::as_str).collect(); + resolve(inputs, fs(&refs)) + } + + #[test] + fn settings_path_wins_over_everything() { + let (inputs, files) = everything(); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Settings); + assert_eq!(found.path, PathBuf::from("/custom/stackql-custom")); + } + + #[test] + fn the_engine_beside_the_app_is_the_default() { + let (mut inputs, files) = everything(); + inputs.settings_path = None; + inputs.env_bin = None; + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Sibling); + assert_eq!(found.path, PathBuf::from("/app").join(BINARY_NAME)); + assert!(!found.env_passed_over); + assert_eq!(found.found_via(), "beside the app"); + } + + #[test] + fn the_engine_beside_the_app_comes_before_the_variable_and_says_so() { + // Everything is there but a path in settings. + let (mut inputs, files) = everything(); + inputs.settings_path = None; + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Sibling); + assert_eq!(found.path, PathBuf::from("/app").join(BINARY_NAME)); + // An engine other than the one the variable names is not run + // without a word. + assert!(found.env_passed_over); + let how = found.found_via(); + assert!(how.starts_with("beside the app"), "{how}"); + assert!(how.contains("STACKQL_BIN is set and not used"), "{how}"); + assert!(how.contains("Settings"), "{how}"); + } + + #[test] + fn a_stale_variable_does_not_stop_the_engine_beside_the_app() { + // Left over from before the install, and pointing nowhere. + let (mut inputs, files) = everything(); + inputs.settings_path = None; + inputs.env_bin = Some(OsString::from("/env/missing")); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Sibling); + assert!(found.env_passed_over); + } + + #[test] + fn the_variable_is_third_and_is_what_a_build_with_no_engine_beside_it_uses() { + let (mut inputs, files) = everything(); + inputs.settings_path = None; + inputs.exe_dir = Some(PathBuf::from("/elsewhere")); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::EnvVar); + assert_eq!(found.path, PathBuf::from("/env/stackql-env")); + assert!(!found.env_passed_over); + } + + /// An app the PKG installed on a Mac, with the command the PKG put down. + const MAC_APP: &str = "/Applications/StackQL Workbench.app/Contents/MacOS/stackql-workbench"; + + fn mac_install() -> (Inputs, Vec) { + let exe = Path::new(MAC_APP); + let pkg_command = bin_in("/usr/local/bin"); + let inputs = Inputs { + settings_path: None, + env_bin: None, + exe_dir: exe.parent().map(Path::to_path_buf), + with_app: installed_with_app(Some(exe), true), + // What the search knows about on a Mac, the PKG's folder included. + well_known: vec![ + PathBuf::from(&pkg_command), + PathBuf::from(bin_in("/opt/homebrew/bin")), + ], + path_var: path_var(&["/usr/bin"]), + }; + (inputs, vec![pkg_command, bin_in("/opt/homebrew/bin")]) + } + + #[test] + fn on_a_mac_only_an_installed_app_has_an_installer_behind_it() { + let app = Path::new(MAC_APP); + assert_eq!( + installed_with_app(Some(app), true), + vec![PathBuf::from(bin_in("/usr/local/bin"))] + ); + // A build from this repository is not in a bundle. + let build = + Path::new("/Users/dev/stackql-workbench/src-tauri/target/debug/stackql-workbench"); + assert!(installed_with_app(Some(build), true).is_empty()); + // The MSI puts the engine beside the app, so Windows has no such place. + assert!(installed_with_app(Some(app), false).is_empty()); + assert!(installed_with_app(None, true).is_empty()); + } + + #[test] + fn on_a_mac_the_installed_app_takes_the_command_the_installer_put_down() { + let (inputs, files) = mac_install(); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::WithApp); + assert_eq!(found.path, PathBuf::from(bin_in("/usr/local/bin"))); + assert_eq!(found.found_via(), "installed with the app"); + } + + #[test] + fn on_a_mac_the_variable_does_not_replace_the_installed_engine_either() { + for value in ["/env/stackql-env", "/env/missing"] { + let (mut inputs, mut files) = mac_install(); + inputs.env_bin = Some(OsString::from(value)); + files.push("/env/stackql-env".to_string()); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::WithApp, "{value}"); + assert!(found.env_passed_over); + assert!( + found + .found_via() + .contains("STACKQL_BIN is set and not used") + ); + } + } + + #[test] + fn on_a_mac_a_path_in_settings_still_wins() { + let (mut inputs, mut files) = mac_install(); + inputs.settings_path = Some(PathBuf::from("/custom/stackql-custom")); + files.push("/custom/stackql-custom".to_string()); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Settings); + } + + #[test] + fn on_a_mac_an_engine_inside_the_bundle_comes_before_the_command() { + // Not where the PKG puts it today. If a later one does, it is found. + let (inputs, mut files) = mac_install(); + let inside = Path::new(MAC_APP) + .with_file_name(BINARY_NAME) + .display() + .to_string(); + files.push(inside.clone()); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Sibling); + assert_eq!(found.path, PathBuf::from(inside)); + } + + #[test] + fn on_a_mac_a_build_from_the_repository_still_tries_the_variable_first() { + // The command is installed on this Mac too, but this build has no + // installer behind it, so what the developer named is used. + let build = + Path::new("/Users/dev/stackql-workbench/src-tauri/target/debug/stackql-workbench"); + let (mut inputs, mut files) = mac_install(); + inputs.exe_dir = build.parent().map(Path::to_path_buf); + inputs.with_app = installed_with_app(Some(build), true); + inputs.env_bin = Some(OsString::from("/env/stackql-env")); + files.push("/env/stackql-env".to_string()); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::EnvVar); + // Without the variable it is found as one of the usual places. + inputs.env_bin = None; + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::WellKnown); + assert_eq!(found.path, PathBuf::from(bin_in("/usr/local/bin"))); + } + + #[test] + fn on_a_mac_an_installed_app_with_no_installed_command_searches_on() { + // The command was removed, or the app was copied over by hand. + let (mut inputs, _) = mac_install(); + let files = vec![bin_in("/opt/homebrew/bin")]; + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::WellKnown); + assert_eq!(found.path, PathBuf::from(bin_in("/opt/homebrew/bin"))); + // And then the variable is back in its place, strict as ever. + inputs.env_bin = Some(OsString::from("/env/missing")); + let err = resolve_with(&inputs, &files).unwrap_err(); + assert!(matches!(err, DiscoveryError::EnvPathInvalid(_))); + } + + #[test] + fn a_path_in_settings_still_wins_over_the_engine_beside_the_app() { + // The operator's own choice, made after the install. + let (inputs, files) = everything(); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Settings); + assert!(!found.env_passed_over); + assert_eq!(found.found_via(), "settings"); + } + + #[test] + fn well_known_is_fourth() { + let (mut inputs, files) = everything(); + inputs.settings_path = None; + inputs.env_bin = None; + inputs.exe_dir = Some(PathBuf::from("/elsewhere")); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::WellKnown); + } + + #[test] + fn path_is_last_and_searched_in_order() { + let (mut inputs, mut files) = everything(); + inputs.settings_path = None; + inputs.env_bin = None; + inputs.exe_dir = None; + inputs.well_known.clear(); + inputs.path_var = path_var(&["/first", "/usr/bin"]); + files.push(bin_in("/first")); + let found = resolve_with(&inputs, &files).unwrap(); + assert_eq!(found.source, Source::Path); + assert_eq!(found.path, PathBuf::from("/first").join(BINARY_NAME)); + } + + #[test] + fn invalid_settings_path_is_an_error_not_a_fallthrough() { + let (mut inputs, files) = everything(); + inputs.settings_path = Some(PathBuf::from("/custom/missing")); + let err = resolve_with(&inputs, &files).unwrap_err(); + assert!(matches!(err, DiscoveryError::SettingsPathInvalid(_))); + } + + #[test] + fn invalid_env_var_is_an_error_not_a_fallthrough() { + // With no engine beside the app the variable is what was asked for, + // and the install location further down is not used in its place. + let (mut inputs, files) = everything(); + inputs.settings_path = None; + inputs.exe_dir = Some(PathBuf::from("/elsewhere")); + inputs.env_bin = Some(OsString::from("/env/missing")); + let err = resolve_with(&inputs, &files).unwrap_err(); + assert!(matches!(err, DiscoveryError::EnvPathInvalid(_))); + } + + #[test] + fn nothing_found_says_so() { + let inputs = Inputs { + path_var: path_var(&["/a", "/b"]), + ..Inputs::default() + }; + assert_eq!(resolve(&inputs, |_| false), Err(DiscoveryError::NotFound)); + assert!(DiscoveryError::NotFound.to_string().contains("Settings")); + } + + #[test] + fn empty_path_entries_are_skipped() { + let inputs = Inputs { + path_var: Some(OsString::from(if cfg!(windows) { ";;" } else { "::" })), + ..Inputs::default() + }; + // An empty entry must not resolve to a binary in the working directory. + assert_eq!(resolve(&inputs, |_| true), Err(DiscoveryError::NotFound)); + } + + #[test] + fn parses_the_version_line() { + let v = + parse_version("stackql v1.0.888 Windows (f7b4116)\nBuildDate: 2026-11-05\n").unwrap(); + assert_eq!(v.version, "1.0.888"); + assert_eq!(v.platform.as_deref(), Some("Windows")); + assert_eq!(v.commit.as_deref(), Some("f7b4116")); + } + + #[test] + fn parses_a_version_line_without_extras() { + let v = parse_version("stackql v0.9.1").unwrap(); + assert_eq!(v.version, "0.9.1"); + assert_eq!(v.platform, None); + assert_eq!(v.commit, None); + } + + #[test] + fn rejects_output_from_another_program() { + assert_eq!(parse_version("psql (PostgreSQL) 16.1"), None); + assert_eq!(parse_version(""), None); + assert_eq!(parse_version("stackql"), None); + assert_eq!(parse_version("stackql unknown"), None); + } + + #[test] + fn well_known_locations_use_the_platform_layout() { + let locations = well_known_locations(|name| match name { + "ProgramFiles" => Some(OsString::from("C:\\Program Files")), + _ => None, + }); + assert!(!locations.is_empty()); + assert!(locations.iter().all(|p| p.ends_with(BINARY_NAME))); + } +} diff --git a/src-tauri/src/engine/job.rs b/src-tauri/src/engine/job.rs new file mode 100644 index 0000000..922be4b --- /dev/null +++ b/src-tauri/src/engine/job.rs @@ -0,0 +1,174 @@ +//! Windows job object that ties child processes to the life of the app. +//! +//! The job is created with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. The app holds +//! the only handle. When the app exits for any reason, including a crash or a +//! forced termination, the OS closes that handle and terminates every process +//! in the job. Nothing in the app has to run for that to happen. + +use std::io; +use std::os::windows::io::RawHandle; + +use windows_sys::Win32::Foundation::{CloseHandle, HANDLE}; +use windows_sys::Win32::System::JobObjects::{ + AssignProcessToJobObject, CreateJobObjectW, JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, + JOBOBJECT_EXTENDED_LIMIT_INFORMATION, JobObjectExtendedLimitInformation, + SetInformationJobObject, +}; + +pub struct Job { + handle: HANDLE, +} + +// SAFETY: a job object handle is a kernel object reference. The kernel +// synchronises access to it, and this type only passes the handle to system +// calls, so it can be shared and sent across threads. +unsafe impl Send for Job {} +// SAFETY: as above. +unsafe impl Sync for Job {} + +impl Job { + /// Creates an anonymous job whose processes die when its last handle closes. + pub fn new() -> io::Result { + // SAFETY: both arguments may be null: default security attributes and + // an unnamed job. + let handle = unsafe { CreateJobObjectW(std::ptr::null(), std::ptr::null()) }; + if handle.is_null() { + return Err(io::Error::last_os_error()); + } + // Wrap the handle first so it is closed if the next call fails. + let job = Self { handle }; + + // SAFETY: the struct is plain data for which all-zero is a valid value. + let mut info: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { std::mem::zeroed() }; + info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE; + let size = u32::try_from(size_of::()) + .map_err(|_| io::Error::other("job limit information size does not fit in u32"))?; + // SAFETY: `info` is a live, correctly sized struct of the type named + // by the information class, and the handle is a valid job handle. + let ok = unsafe { + SetInformationJobObject( + job.handle, + JobObjectExtendedLimitInformation, + (&raw const info).cast(), + size, + ) + }; + if ok == 0 { + return Err(io::Error::last_os_error()); + } + Ok(job) + } + + /// Puts a running process into the job. Processes it starts later join + /// the job as well. + pub fn assign(&self, process: RawHandle) -> io::Result<()> { + // SAFETY: the job handle is valid for the life of `self`. The caller + // passes a process handle obtained from a live child. + let ok = unsafe { AssignProcessToJobObject(self.handle, process as HANDLE) }; + if ok == 0 { + return Err(io::Error::last_os_error()); + } + Ok(()) + } +} + +impl Drop for Job { + fn drop(&mut self) { + // SAFETY: the handle was returned by CreateJobObjectW and is closed + // exactly once, here. + unsafe { + CloseHandle(self.handle); + } + } +} + +#[cfg(test)] +mod tests { + use std::os::windows::io::AsRawHandle; + use std::process::{Command, Stdio}; + use std::time::{Duration, Instant}; + + use super::*; + + fn long_running_child() -> std::process::Child { + // `ping -n 60` runs for about a minute and needs no console input. + Command::new("ping") + .args(["-n", "60", "127.0.0.1"]) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap() + } + + fn wait_for_exit(child: &mut std::process::Child, within: Duration) -> bool { + let deadline = Instant::now() + within; + while Instant::now() < deadline { + if child.try_wait().unwrap().is_some() { + return true; + } + std::thread::sleep(Duration::from_millis(20)); + } + false + } + + #[test] + fn a_process_in_another_job_can_join_an_empty_job_but_not_a_used_one() { + // The child starts out in a job of its own, as a packaged app does. + let theirs = Job::new().unwrap(); + let mut child = long_running_child(); + theirs.assign(child.as_raw_handle()).unwrap(); + + // A job that already has a member will not take it. + let used = Job::new().unwrap(); + let mut member = long_running_child(); + used.assign(member.as_raw_handle()).unwrap(); + assert!( + used.assign(child.as_raw_handle()).is_err(), + "a used job took a process from another job" + ); + + // An empty one will, and closing it still kills the process. + let empty = Job::new().unwrap(); + empty.assign(child.as_raw_handle()).unwrap(); + drop(empty); + assert!( + wait_for_exit(&mut child, Duration::from_secs(5)), + "the process outlived the job it was put in" + ); + + drop(used); + assert!(wait_for_exit(&mut member, Duration::from_secs(5))); + drop(theirs); + } + + #[test] + fn closing_the_job_kills_its_processes() { + let job = Job::new().unwrap(); + let mut child = long_running_child(); + job.assign(child.as_raw_handle()).unwrap(); + assert!( + child.try_wait().unwrap().is_none(), + "child should be running" + ); + + // Dropping the job closes the only handle, which is exactly what the + // OS does when the app is terminated. + drop(job); + + assert!( + wait_for_exit(&mut child, Duration::from_secs(5)), + "child should die when the job handle closes" + ); + } + + #[test] + fn a_process_outside_the_job_survives_it() { + let job = Job::new().unwrap(); + let mut child = long_running_child(); + drop(job); + assert!(!wait_for_exit(&mut child, Duration::from_millis(300))); + child.kill().unwrap(); + child.wait().unwrap(); + } +} diff --git a/src-tauri/src/engine/logbuf.rs b/src-tauri/src/engine/logbuf.rs new file mode 100644 index 0000000..e8a85af --- /dev/null +++ b/src-tauri/src/engine/logbuf.rs @@ -0,0 +1,107 @@ +//! A bounded buffer of lines captured from a child's stderr. + +use std::collections::VecDeque; +use std::sync::{Arc, Mutex}; + +use crate::util::{lock, truncate}; + +const MAX_LINES: usize = 1000; +const MAX_LINE_CHARS: usize = 4000; + +#[derive(Debug, Default)] +struct Inner { + lines: VecDeque<(u64, String)>, + next_seq: u64, +} + +/// Keeps the most recent stderr lines of one child. Each line has a sequence +/// number so a caller can ask for "everything since this point", which is how +/// engine output gets attached to the statement that was running at the time. +#[derive(Debug, Clone, Default)] +pub struct LogBuffer { + inner: Arc>, +} + +impl LogBuffer { + pub fn push(&self, line: &str) { + let mut inner = lock(&self.inner); + let seq = inner.next_seq; + inner.next_seq += 1; + inner.lines.push_back((seq, truncate(line, MAX_LINE_CHARS))); + while inner.lines.len() > MAX_LINES { + inner.lines.pop_front(); + } + } + + /// The sequence number the next line will get. + pub fn mark(&self) -> u64 { + lock(&self.inner).next_seq + } + + /// Lines pushed at or after `mark`, oldest first. + pub fn since(&self, mark: u64) -> Vec { + lock(&self.inner) + .lines + .iter() + .filter(|(seq, _)| *seq >= mark) + .map(|(_, line)| line.clone()) + .collect() + } + + /// The last `count` lines, oldest first. + pub fn tail(&self, count: usize) -> Vec { + let inner = lock(&self.inner); + let skip = inner.lines.len().saturating_sub(count); + inner + .lines + .iter() + .skip(skip) + .map(|(_, line)| line.clone()) + .collect() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn since_returns_lines_after_the_mark() { + let buf = LogBuffer::default(); + buf.push("one"); + let mark = buf.mark(); + buf.push("two"); + buf.push("three"); + assert_eq!(buf.since(mark), vec!["two", "three"]); + assert_eq!(buf.since(buf.mark()), Vec::::new()); + } + + #[test] + fn tail_returns_the_most_recent_lines() { + let buf = LogBuffer::default(); + for i in 0..5 { + buf.push(&format!("line {i}")); + } + assert_eq!(buf.tail(2), vec!["line 3", "line 4"]); + assert_eq!(buf.tail(100).len(), 5); + } + + #[test] + fn is_bounded() { + let buf = LogBuffer::default(); + for i in 0..(MAX_LINES + 50) { + buf.push(&format!("{i}")); + } + assert_eq!(buf.tail(usize::MAX).len(), MAX_LINES); + assert_eq!(buf.tail(1), vec![format!("{}", MAX_LINES + 49)]); + // A mark taken before the overflow still works, it just sees less. + assert_eq!(buf.since(0).len(), MAX_LINES); + } + + #[test] + fn long_lines_are_cut() { + let buf = LogBuffer::default(); + buf.push(&"x".repeat(MAX_LINE_CHARS + 10)); + assert_eq!(buf.tail(1)[0].chars().count(), MAX_LINE_CHARS + 3); + } +} diff --git a/src-tauri/src/engine/mod.rs b/src-tauri/src/engine/mod.rs new file mode 100644 index 0000000..1a37303 --- /dev/null +++ b/src-tauri/src/engine/mod.rs @@ -0,0 +1,38 @@ +//! Engine discovery and process lifecycle. +//! +//! Nothing outside `connection::local` should need this module: code above +//! the `Connection` trait must not assume the engine is a child process. + +pub mod approot; +pub mod discovery; +pub mod logbuf; +pub mod port; +pub mod supervisor; + +#[cfg(windows)] +mod job; +#[cfg(unix)] +mod watchdog; + +/// Whether a file is inside a macOS app bundle: one of the folders it sits in +/// is named `.app`. An app that an installer put down runs from a +/// bundle. A build from this repository does not. +pub fn in_app_bundle(file: &std::path::Path) -> bool { + file.ancestors() + .skip(1) + .any(|part| part.extension().is_some_and(|ext| ext == "app")) +} + +/// Stops Windows from opening a console window for a console program started +/// by a GUI app. Does nothing on other platforms. +pub fn hide_console_window(cmd: &mut tokio::process::Command) { + #[cfg(windows)] + { + const CREATE_NO_WINDOW: u32 = 0x0800_0000; + cmd.creation_flags(CREATE_NO_WINDOW); + } + #[cfg(not(windows))] + { + let _ = cmd; + } +} diff --git a/src-tauri/src/engine/port.rs b/src-tauri/src/engine/port.rs new file mode 100644 index 0000000..7a4b823 --- /dev/null +++ b/src-tauri/src/engine/port.rs @@ -0,0 +1,45 @@ +//! Choosing a free loopback port for the engine. + +use std::io; +use std::net::{Ipv4Addr, SocketAddrV4, TcpListener}; + +/// Asks the OS for a free port on 127.0.0.1 and releases it again. +/// +/// There is a small window between releasing the port and the engine binding +/// it in which another process could take it. The supervisor's readiness +/// check catches that case: the engine fails to bind, exits, and the failure +/// is reported with its stderr. +pub fn pick_free_port() -> io::Result { + let listener = TcpListener::bind(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 0))?; + Ok(listener.local_addr()?.port()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn picks_a_port_that_can_be_bound_again() { + let port = pick_free_port().unwrap(); + assert_ne!(port, 0); + // The port was released, so binding it must succeed. + let rebound = TcpListener::bind(SocketAddrV4::new(Ipv4Addr::LOCALHOST, port)); + assert!(rebound.is_ok(), "port {port} should be free"); + } + + #[test] + fn does_not_hand_out_a_port_that_is_in_use() { + let held = TcpListener::bind(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 0)).unwrap(); + let held_port = held.local_addr().unwrap().port(); + for _ in 0..50 { + assert_ne!(pick_free_port().unwrap(), held_port); + } + } + + #[test] + fn picks_from_the_loopback_interface_only() { + // Binding 127.0.0.1:0 must never yield a privileged port. + let port = pick_free_port().unwrap(); + assert!(port >= 1024); + } +} diff --git a/src-tauri/src/engine/supervisor.rs b/src-tauri/src/engine/supervisor.rs new file mode 100644 index 0000000..840b1d9 --- /dev/null +++ b/src-tauri/src/engine/supervisor.rs @@ -0,0 +1,546 @@ +//! The one owner of every child process. +//! +//! Guarantees: +//! +//! - A child never outlives the app. On Windows every child is placed in a +//! job object that the OS tears down when the app's handle closes. On Unix +//! every child leads its own process group and has a watchdog that signals +//! the group when the app dies. Both work when the app is force-quit. +//! - stderr of every child is captured. +//! - For a stdio child, stdin and stdout are handed to the caller untouched, +//! because they carry protocol frames. + +use std::ffi::OsString; +use std::path::PathBuf; +use std::process::Stdio; +use std::time::Duration; + +use tokio::io::{AsyncBufReadExt, BufReader}; +use tokio::process::{ChildStdin, ChildStdout, Command}; +use tokio::sync::{oneshot, watch}; + +use super::logbuf::LogBuffer; + +#[derive(Debug, thiserror::Error)] +pub enum SupervisorError { + #[error("Could not set up process supervision: {0}")] + Setup(std::io::Error), + #[error("Could not start {program}: {source}")] + Spawn { + program: String, + source: std::io::Error, + }, + #[error("Started {program} but could not tie it to the app, so it was stopped: {source}")] + Tie { + program: String, + source: std::io::Error, + }, +} + +/// How a child's stdin and stdout are connected. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum StdioMode { + /// Both closed. For a server that is reached over a socket. + Detached, + /// Both piped to the caller. For a server that speaks over stdio. + Piped, +} + +/// The environment a child starts with. It is always built explicitly here, +/// never left to chance. +#[derive(Debug, Clone, Default)] +pub struct EnvSpec { + /// Start from the app's own environment. On macOS an app launched from + /// Finder has almost nothing in it, so this must not be relied on for + /// credentials. + pub inherit: bool, + /// Variables set on top. Values are never logged. + pub vars: Vec<(String, String)>, +} + +#[derive(Debug, Clone)] +pub struct ChildSpec { + pub program: PathBuf, + pub args: Vec, + pub env: EnvSpec, + pub cwd: PathBuf, + pub stdio: StdioMode, +} + +/// How a child ended. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ExitInfo { + pub code: Option, + /// True when the supervisor stopped the child on request. + pub requested: bool, +} + +pub struct Supervisor { + #[cfg(windows)] + job: super::job::Job, +} + +impl Supervisor { + pub fn new() -> Result { + Ok(Self { + #[cfg(windows)] + job: super::job::Job::new().map_err(SupervisorError::Setup)?, + }) + } + + /// Starts a child and ties its life to the app. Must be called from + /// within the tokio runtime. + pub fn spawn(&self, spec: &ChildSpec) -> Result { + let program = spec.program.display().to_string(); + let mut cmd = Command::new(&spec.program); + cmd.args(&spec.args) + .current_dir(&spec.cwd) + .stderr(Stdio::piped()) + // Covers the case where the runtime drops the monitor task. + .kill_on_drop(true); + match spec.stdio { + StdioMode::Detached => { + cmd.stdin(Stdio::null()).stdout(Stdio::null()); + } + StdioMode::Piped => { + cmd.stdin(Stdio::piped()).stdout(Stdio::piped()); + } + } + if !spec.env.inherit { + cmd.env_clear(); + } + cmd.envs(spec.env.vars.iter().map(|(k, v)| (k, v))); + super::hide_console_window(&mut cmd); + #[cfg(unix)] + cmd.process_group(0); + + let mut child = cmd.spawn().map_err(|source| SupervisorError::Spawn { + program: program.clone(), + source, + })?; + + // A process that starts out in a job of its own cannot join a job + // that already has members. A packaged Windows app does that, and a + // program on PATH can be an alias for one. Such a child gets a job + // to itself, which an empty job always allows, with the same rule: + // it dies when the app's handle to the job closes. + #[cfg(windows)] + let own_job = match child.raw_handle() { + Some(handle) if self.job.assign(handle).is_err() => { + let job = super::job::Job::new().and_then(|job| job.assign(handle).map(|()| job)); + match job { + Ok(job) => Some(job), + Err(source) => { + let _ = child.start_kill(); + return Err(SupervisorError::Tie { program, source }); + } + } + } + _ => None, + }; + + #[cfg(unix)] + let watchdog = match child.id().map(super::watchdog::Watchdog::spawn) { + Some(Ok(watchdog)) => Some(watchdog), + Some(Err(source)) => { + let _ = child.start_kill(); + return Err(SupervisorError::Tie { program, source }); + } + // The child has already exited. There is nothing to watch. + None => None, + }; + + let pid = child.id(); + let stderr = LogBuffer::default(); + if let Some(pipe) = child.stderr.take() { + let sink = stderr.clone(); + tokio::spawn(async move { + let mut lines = BufReader::new(pipe).lines(); + while let Ok(Some(line)) = lines.next_line().await { + sink.push(&line); + } + }); + } + let stdin = child.stdin.take(); + let stdout = child.stdout.take(); + + let (exit_tx, exit_rx) = watch::channel(None); + let (stop_tx, stop_rx) = oneshot::channel::<()>(); + tokio::spawn(async move { + let info = tokio::select! { + status = child.wait() => ExitInfo { + code: status.ok().and_then(|s| s.code()), + requested: false, + }, + // Resolves on an explicit stop and also when the owner drops + // the handle. Either way the child must go. + _ = stop_rx => { + let _ = child.kill().await; + ExitInfo { code: None, requested: true } + } + }; + #[cfg(unix)] + if let Some(watchdog) = watchdog { + watchdog.disarm().await; + } + // Closing a job the child had to itself ends whatever the child + // left running. + #[cfg(windows)] + drop(own_job); + let _ = exit_tx.send(Some(info)); + }); + + Ok(ManagedChild { + pid, + stderr, + stdin, + stdout, + exit: exit_rx, + stop: Some(stop_tx), + }) + } +} + +/// A running child. Dropping it stops the child. +pub struct ManagedChild { + pub pid: Option, + pub stderr: LogBuffer, + /// Present for `StdioMode::Piped` until the caller takes it. + pub stdin: Option, + /// Present for `StdioMode::Piped` until the caller takes it. + pub stdout: Option, + exit: watch::Receiver>, + stop: Option>, +} + +impl ManagedChild { + /// How the child ended, if it has. + pub fn exit_info(&self) -> Option { + self.exit.borrow().clone() + } + + /// A receiver that changes when the child exits. + pub fn exit_watch(&self) -> watch::Receiver> { + self.exit.clone() + } + + /// Stops the child and waits for it to be gone. + pub async fn stop(&mut self) { + if let Some(stop) = self.stop.take() { + let _ = stop.send(()); + } + let mut exit = self.exit.clone(); + let _ = tokio::time::timeout(Duration::from_secs(5), async { + while exit.borrow().is_none() { + if exit.changed().await.is_err() { + break; + } + } + }) + .await; + } +} + +#[cfg(test)] +mod tests { + use std::time::Instant; + + use super::*; + + fn spec(program: &str, args: &[&str]) -> ChildSpec { + ChildSpec { + program: PathBuf::from(program), + args: args.iter().map(OsString::from).collect(), + env: EnvSpec { + inherit: true, + vars: Vec::new(), + }, + cwd: std::env::temp_dir(), + stdio: StdioMode::Detached, + } + } + + fn sleeper() -> ChildSpec { + if cfg!(windows) { + spec("ping", &["-n", "60", "127.0.0.1"]) + } else { + spec("/bin/sleep", &["60"]) + } + } + + fn shell(script: &str) -> ChildSpec { + if cfg!(windows) { + spec("cmd", &["/C", script]) + } else { + spec("/bin/sh", &["-c", script]) + } + } + + /// A process a test watches for its end. + /// + /// On Windows this holds a handle to the process and waits on it. Asking + /// `tasklist` instead starts a program for every look, and on a busy + /// machine that alone could use up the time a test allows. The handle + /// also keeps the process id from going to another process meanwhile. + struct Watched { + #[cfg(windows)] + handle: windows_sys::Win32::Foundation::HANDLE, + #[cfg(not(windows))] + pid: u32, + } + + #[cfg(windows)] + impl Watched { + /// Starts watching. `None` when no process has this id. + fn open(pid: u32) -> Option { + use windows_sys::Win32::System::Threading::{OpenProcess, PROCESS_SYNCHRONIZE}; + // SAFETY: the arguments are plain values, and the handle that + // comes back is checked before it is kept. + let handle = unsafe { OpenProcess(PROCESS_SYNCHRONIZE, 0, pid) }; + (!handle.is_null()).then_some(Self { handle }) + } + + fn alive(&self) -> bool { + use windows_sys::Win32::Foundation::WAIT_OBJECT_0; + use windows_sys::Win32::System::Threading::WaitForSingleObject; + // SAFETY: the handle stays open for as long as `self` lives. A + // wait of zero milliseconds reports the state and returns. + let state = unsafe { WaitForSingleObject(self.handle, 0) }; + // A process handle is signalled once the process has ended. A + // wait that fails counts as alive, so it can only fail a test. + state != WAIT_OBJECT_0 + } + } + + #[cfg(windows)] + impl Drop for Watched { + fn drop(&mut self) { + // SAFETY: the handle came from OpenProcess and is closed once. + unsafe { windows_sys::Win32::Foundation::CloseHandle(self.handle) }; + } + } + + #[cfg(not(windows))] + impl Watched { + /// Starts watching. `None` when no process has this id. + fn open(pid: u32) -> Option { + let watched = Self { pid }; + watched.alive().then_some(watched) + } + + fn alive(&self) -> bool { + std::process::Command::new("/bin/kill") + .args(["-0", &self.pid.to_string()]) + .stderr(Stdio::null()) + .status() + .unwrap() + .success() + } + } + + impl Watched { + /// Whether the process ends within the time given. + async fn gone_within(&self, within: Duration) -> bool { + let deadline = Instant::now() + within; + loop { + if !self.alive() { + return true; + } + if Instant::now() >= deadline { + return false; + } + // Sleeping here lets the task that ends the child run. + tokio::time::sleep(Duration::from_millis(20)).await; + } + } + } + + #[tokio::test] + async fn stop_ends_the_child() { + let supervisor = Supervisor::new().unwrap(); + let mut child = supervisor.spawn(&sleeper()).unwrap(); + let watched = Watched::open(child.pid.unwrap()).expect("the child should be running"); + assert!(watched.alive()); + + child.stop().await; + + assert_eq!( + child.exit_info(), + Some(ExitInfo { + code: None, + requested: true + }) + ); + assert!(watched.gone_within(Duration::from_secs(5)).await); + } + + #[tokio::test] + async fn dropping_the_handle_ends_the_child() { + let supervisor = Supervisor::new().unwrap(); + let child = supervisor.spawn(&sleeper()).unwrap(); + let watched = Watched::open(child.pid.unwrap()).expect("the child should be running"); + drop(child); + assert!(watched.gone_within(Duration::from_secs(5)).await); + } + + #[tokio::test] + async fn an_unexpected_exit_is_reported_with_its_code() { + let supervisor = Supervisor::new().unwrap(); + let child = supervisor.spawn(&shell("exit 3")).unwrap(); + let mut exit = child.exit_watch(); + tokio::time::timeout(Duration::from_secs(10), async { + while exit.borrow().is_none() { + exit.changed().await.unwrap(); + } + }) + .await + .unwrap(); + assert_eq!( + child.exit_info(), + Some(ExitInfo { + code: Some(3), + requested: false + }) + ); + } + + #[tokio::test] + async fn stderr_is_captured() { + let supervisor = Supervisor::new().unwrap(); + let child = supervisor + .spawn(&shell("echo engine-said-this 1>&2")) + .unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + let lines = child.stderr.tail(10); + if lines.iter().any(|l| l.contains("engine-said-this")) { + break; + } + assert!( + Instant::now() < deadline, + "stderr line not captured: {lines:?}" + ); + tokio::time::sleep(Duration::from_millis(20)).await; + } + } + + #[tokio::test] + async fn explicit_environment_does_not_leak_the_parent_environment() { + let supervisor = Supervisor::new().unwrap(); + // A variable the parent certainly has, and the child must not see. + let (parent_var, script) = if cfg!(windows) { + ( + "USERNAME", + "echo marker [%USERNAME%] [%WB_TEST_EXTRA%] 1>&2", + ) + } else { + ("HOME", "echo marker [$HOME] [$WB_TEST_EXTRA] 1>&2") + }; + let Ok(parent_value) = std::env::var(parent_var) else { + return; + }; + let mut spec = shell(script); + spec.env = EnvSpec { + inherit: false, + vars: vec![ + ("WB_TEST_EXTRA".to_string(), "set".to_string()), + // cmd.exe does not start without this. + ( + "SystemRoot".to_string(), + std::env::var("SystemRoot").unwrap_or_default(), + ), + ], + }; + let child = supervisor.spawn(&spec).unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + let lines = child.stderr.tail(10); + if let Some(line) = lines.iter().find(|l| l.contains("marker")) { + assert!(line.contains("[set]"), "explicit variable missing: {line}"); + assert!( + !line.contains(&format!("[{parent_value}]")), + "parent environment leaked into the child" + ); + break; + } + assert!(Instant::now() < deadline, "no output: {lines:?}"); + tokio::time::sleep(Duration::from_millis(20)).await; + } + } + + #[tokio::test] + async fn a_missing_program_is_a_spawn_error() { + let supervisor = Supervisor::new().unwrap(); + let err = supervisor + .spawn(&spec("definitely-not-a-real-program-xyz", &[])) + .err() + .unwrap(); + assert!(matches!(err, SupervisorError::Spawn { .. })); + } + + /// Not a test in its own right. When the variable is set, this process + /// plays the app: it supervises a child, prints the child's pid, and then + /// waits to be killed. + #[tokio::test] + async fn helper_app_that_waits_to_be_killed() { + if std::env::var_os("WB_SUPERVISOR_HELPER").is_none() { + return; + } + let supervisor = Supervisor::new().unwrap(); + let child = supervisor.spawn(&sleeper()).unwrap(); + println!("CHILD_PID={}", child.pid.unwrap()); + tokio::time::sleep(Duration::from_secs(120)).await; + } + + /// The force-quit guarantee, end to end: start a stand-in for the app, + /// kill it without giving it a chance to clean up, and check that the + /// child it supervised is gone. + #[tokio::test] + async fn killing_the_app_kills_its_children() { + use tokio::io::AsyncBufReadExt; + + let mut app = tokio::process::Command::new(std::env::current_exe().unwrap()) + .args([ + "--exact", + "engine::supervisor::tests::helper_app_that_waits_to_be_killed", + "--nocapture", + "--test-threads=1", + ]) + .env("WB_SUPERVISOR_HELPER", "1") + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::null()) + // If an assertion below fails, do not leave the helper behind. + .kill_on_drop(true) + .spawn() + .unwrap(); + + let stdout = app.stdout.take().unwrap(); + let mut lines = BufReader::new(stdout).lines(); + let child_pid: u32 = tokio::time::timeout(Duration::from_secs(60), async { + loop { + let line = lines + .next_line() + .await + .unwrap() + .expect("helper exited early"); + // The test harness prints the test name on the same line first. + if let Some((_, pid)) = line.split_once("CHILD_PID=") { + return pid.trim().parse().unwrap(); + } + } + }) + .await + .expect("helper did not report a child pid"); + let watched = Watched::open(child_pid).expect("supervised child should be running"); + assert!(watched.alive(), "supervised child should be running"); + + // TerminateProcess on Windows, SIGKILL on Unix. No cleanup code runs. + app.kill().await.unwrap(); + + assert!( + watched.gone_within(Duration::from_secs(10)).await, + "supervised child {child_pid} outlived the app" + ); + } +} diff --git a/src-tauri/src/engine/watchdog.rs b/src-tauri/src/engine/watchdog.rs new file mode 100644 index 0000000..52530ad --- /dev/null +++ b/src-tauri/src/engine/watchdog.rs @@ -0,0 +1,133 @@ +//! Unix watchdog that kills a child's process group when the app dies. +//! +//! A process group alone is not enough on macOS: when the app receives +//! SIGKILL, nothing signals its children, and macOS has no parent-death +//! signal to ask for. So each supervised child gets a small watchdog process. +//! +//! The watchdog is `/bin/sh` reading from a pipe. The app holds the only +//! write end. While the app lives, the read blocks. When the app exits for +//! any reason, the kernel closes the write end, the read sees end of file, +//! and the watchdog signals the child's process group: SIGTERM first, then +//! SIGKILL two seconds later. +//! +//! Standard pipes are created close-on-exec, so no other child inherits the +//! write end and keeps the pipe open by accident. +//! +//! The watchdog runs in its own process group so that a terminal interrupt +//! aimed at the app's group does not take it out before it has done its job. +//! +//! Residual risk: if the child has already exited and the OS has reused its +//! process group id by the time the watchdog fires, the signal would go to +//! an unrelated group. The supervisor avoids this in the normal case by +//! stopping the watchdog itself before it lets go of a child. + +use std::io; +use std::process::Stdio; + +use tokio::process::{Child, ChildStdin, Command}; + +// `kill -s NAME -- -PGID` is the POSIX spelling. The shorter `kill -TERM -- +// -PGID` is rejected by dash, which is /bin/sh on many Linux systems, so the +// form matters even though macOS ships a different shell. +const SCRIPT: &str = r#"cat >/dev/null 2>&1 +kill -s TERM -- "-$0" 2>/dev/null +sleep 2 +kill -s KILL -- "-$0" 2>/dev/null +exit 0"#; + +pub struct Watchdog { + process: Child, + /// Held open for the life of the app. Closing it fires the watchdog. + lifeline: Option, +} + +impl Watchdog { + /// Starts a watchdog for the process group `pgid`. + pub fn spawn(pgid: u32) -> io::Result { + let mut cmd = Command::new("/bin/sh"); + cmd.arg("-c") + .arg(SCRIPT) + .arg(pgid.to_string()) + .stdin(Stdio::piped()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .process_group(0) + .kill_on_drop(false); + let mut process = cmd.spawn()?; + let lifeline = process.stdin.take(); + if lifeline.is_none() { + return Err(io::Error::other("watchdog has no stdin pipe")); + } + Ok(Self { process, lifeline }) + } + + /// Stops the watchdog without firing it. Call this after the supervised + /// child has been stopped in the normal way. + pub async fn disarm(mut self) { + // Kill first, then drop the pipe, so the script never reaches `kill`. + let _ = self.process.kill().await; + self.lifeline.take(); + } + + /// Closes the pipe, which is what the kernel does when the app dies. + #[cfg(test)] + pub fn fire(&mut self) { + self.lifeline.take(); + } +} + +#[cfg(test)] +mod tests { + use std::time::{Duration, Instant}; + + use super::*; + + async fn exited_within(child: &mut Child, within: Duration) -> bool { + let deadline = Instant::now() + within; + while Instant::now() < deadline { + if child.try_wait().unwrap().is_some() { + return true; + } + tokio::time::sleep(Duration::from_millis(20)).await; + } + false + } + + fn sleeper() -> Child { + Command::new("/bin/sleep") + .arg("60") + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .process_group(0) + .spawn() + .unwrap() + } + + #[tokio::test] + async fn closing_the_lifeline_kills_the_process_group() { + let mut child = sleeper(); + let pgid = child.id().unwrap(); + let mut watchdog = Watchdog::spawn(pgid).unwrap(); + assert!(child.try_wait().unwrap().is_none()); + + watchdog.fire(); + + assert!( + exited_within(&mut child, Duration::from_secs(5)).await, + "child should die when the lifeline closes" + ); + } + + #[tokio::test] + async fn disarming_leaves_the_process_group_alone() { + let mut child = sleeper(); + let pgid = child.id().unwrap(); + let watchdog = Watchdog::spawn(pgid).unwrap(); + + watchdog.disarm().await; + + assert!(!exited_within(&mut child, Duration::from_millis(500)).await); + child.kill().await.unwrap(); + } +} diff --git a/src-tauri/src/error.rs b/src-tauri/src/error.rs new file mode 100644 index 0000000..1b164df --- /dev/null +++ b/src-tauri/src/error.rs @@ -0,0 +1,99 @@ +//! The error type that crosses IPC. + +use serde::Serialize; +use serde::ser::SerializeStruct; + +/// An error the webview can show. It serialises as +/// `{ "kind": ..., "message": ... }`, so the UI can branch on the kind +/// without parsing text and always has a message to display. +#[derive(Debug, Clone, thiserror::Error, PartialEq, Eq)] +pub enum HostError { + /// No `stackql` binary could be resolved. + #[error("{0}")] + EngineNotFound(String), + /// The engine was found but did not start or did not become ready. + #[error("{0}")] + EngineStart(String), + /// A request needed a running engine and there was none. + #[error("The engine is not running.")] + EngineNotRunning, + /// The statement could not be sent or its result could not be read. + #[error("{0}")] + Query(String), + /// A statement is already running on the editor session. + #[error("A statement is already running.")] + Busy, + /// A name from the UI was not a valid identifier. + #[error("{0}")] + InvalidIdentifier(String), + /// Settings could not be read or written. + #[error("{0}")] + Settings(String), + /// The agent runtime failed. + #[error("{0}")] + Agent(String), + /// A secret could not be read from or written to the OS keychain. + #[error("{0}")] + Secrets(String), + /// Anything else. + #[error("{0}")] + Internal(String), +} + +impl HostError { + /// A stable identifier for the variant. + pub fn kind(&self) -> &'static str { + match self { + Self::EngineNotFound(_) => "engineNotFound", + Self::EngineStart(_) => "engineStart", + Self::EngineNotRunning => "engineNotRunning", + Self::Query(_) => "query", + Self::Busy => "busy", + Self::InvalidIdentifier(_) => "invalidIdentifier", + Self::Settings(_) => "settings", + Self::Agent(_) => "agent", + Self::Secrets(_) => "secrets", + Self::Internal(_) => "internal", + } + } +} + +impl Serialize for HostError { + fn serialize(&self, serializer: S) -> Result { + let mut state = serializer.serialize_struct("HostError", 2)?; + state.serialize_field("kind", self.kind())?; + state.serialize_field("message", &self.to_string())?; + state.end() + } +} + +impl From for HostError { + fn from(err: std::io::Error) -> Self { + Self::Internal(err.to_string()) + } +} + +pub type HostResult = Result; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn serialises_with_kind_and_message() { + let json = serde_json::to_value(HostError::EngineNotFound("nope".into())).unwrap(); + assert_eq!( + json, + serde_json::json!({ "kind": "engineNotFound", "message": "nope" }) + ); + } + + #[test] + fn variants_without_data_still_carry_a_message() { + let json = serde_json::to_value(HostError::Busy).unwrap(); + assert_eq!( + json, + serde_json::json!({ "kind": "busy", "message": "A statement is already running." }) + ); + } +} diff --git a/src-tauri/src/icons/directory.rs b/src-tauri/src/icons/directory.rs new file mode 100644 index 0000000..d6196ce --- /dev/null +++ b/src-tauri/src/icons/directory.rs @@ -0,0 +1,382 @@ +//! The provider dictionary published by stackql.io, and the pure logic for +//! turning a provider name into an icon. +//! +//! The dictionary is a list of categories. Each category lists providers +//! with a display name, the address of the provider's documentation site and +//! the path of its icon on stackql.io: +//! +//! ```json +//! { "name": "Databricks Account", +//! "registryAliases": ["databricks"], +//! "href": "https://databricks-account-provider.stackql.io/", +//! "icon": "/img/providers/databricks/favicon.ico", +//! "invertOnDark": true } +//! ``` +//! +//! It does not carry the engine's provider name. That is derived from the +//! documentation address: `databricks-account-provider.stackql.io` is the +//! provider `databricks_account`. + +use std::collections::HashMap; + +use base64::Engine; +use serde::Deserialize; + +/// Where the dictionary is published. +pub const DICTIONARY_URL: &str = + "https://raw.githubusercontent.com/stackql/stackql.io/main/src/configs/providers.json"; + +/// Icon paths in the dictionary are relative to this site. +pub const ICON_BASE: &str = "https://stackql.io"; + +/// A copy of the dictionary taken when the app was built. Used when the +/// published one cannot be fetched. +pub const SNAPSHOT: &str = include_str!("providers.snapshot.json"); + +const DOC_HOST_SUFFIX: &str = "-provider.stackql.io"; +const ICON_EXTENSIONS: [&str; 6] = ["ico", "png", "svg", "jpg", "jpeg", "webp"]; + +#[derive(Debug, Deserialize)] +struct RawCategory { + #[serde(default)] + providers: Vec, +} + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct RawProvider { + #[serde(default)] + name: String, + #[serde(default)] + href: String, + #[serde(default)] + icon: String, + #[serde(default)] + registry_aliases: Vec, + #[serde(default)] + invert_on_dark: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Entry { + pub display_name: String, + /// Path on [`ICON_BASE`], already checked by [`safe_icon_path`]. + pub icon_path: String, + /// The icon is dark on a transparent background and needs inverting on a + /// dark surface. + pub invert_on_dark: bool, +} + +#[derive(Debug, Default)] +pub struct Directory { + by_provider: HashMap, +} + +impl Directory { + /// Parses the dictionary. Entries without a usable icon path are skipped. + pub fn parse(json: &str) -> Result { + let categories: Vec = serde_json::from_str(json) + .map_err(|err| format!("not a provider dictionary: {err}"))?; + let mut by_provider = HashMap::new(); + let mut by_icon_folder = Vec::new(); + + for raw in categories.into_iter().flat_map(|c| c.providers) { + let Some(icon_path) = safe_icon_path(&raw.icon) else { + continue; + }; + let entry = Entry { + display_name: raw.name, + icon_path, + invert_on_dark: raw.invert_on_dark, + }; + let names = provider_from_href(&raw.href) + .into_iter() + .chain(raw.registry_aliases.iter().map(|alias| normalise(alias))); + for name in names { + by_provider.entry(name).or_insert_with(|| entry.clone()); + } + if let Some(folder) = icon_folder(&entry.icon_path) { + by_icon_folder.push((folder, entry)); + } + } + + // The icon folder is usually the provider name too. It only fills + // gaps, so it never overrides a name taken from a documentation address. + for (folder, entry) in by_icon_folder { + by_provider.entry(folder).or_insert(entry); + } + + if by_provider.is_empty() { + return Err("the provider dictionary has no usable entries".to_string()); + } + Ok(Self { by_provider }) + } + + /// Finds the entry for an engine provider name such as `entra_id`. + pub fn lookup(&self, provider: &str) -> Option<&Entry> { + self.by_provider.get(&normalise(provider)) + } + + pub fn len(&self) -> usize { + self.by_provider.len() + } + + pub fn is_empty(&self) -> bool { + self.by_provider.is_empty() + } +} + +/// Provider names use underscores. Documentation addresses use hyphens. +pub fn normalise(name: &str) -> String { + name.trim().to_ascii_lowercase().replace('-', "_") +} + +/// `https://azure-stack-provider.stackql.io/` is the provider `azure_stack`. +fn provider_from_href(href: &str) -> Option { + let rest = href.strip_prefix("https://")?; + let host = rest.split(['/', '?', '#']).next()?; + let slug = host.strip_suffix(DOC_HOST_SUFFIX)?; + if slug.is_empty() { + return None; + } + Some(normalise(slug)) +} + +/// `/img/providers/aws/favicon.ico` is in the folder `aws`. +fn icon_folder(icon_path: &str) -> Option { + let rest = icon_path.strip_prefix("/img/providers/")?; + let (folder, _) = rest.split_once('/')?; + Some(normalise(folder)) +} + +/// Accepts only a plain path to an image under `/img/` on the icon site. +/// +/// The dictionary is fetched from the network, so its contents are not +/// trusted to name an arbitrary address. A full URL, a path that climbs out +/// with `..`, a query string or an unexpected file type is refused. +pub fn safe_icon_path(path: &str) -> Option { + let path = path.trim(); + if !path.starts_with("/img/") || path.contains("..") || path.contains("//") { + return None; + } + let plain = path + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, '/' | '_' | '-' | '.')); + if !plain { + return None; + } + let extension = path.rsplit('.').next()?.to_ascii_lowercase(); + ICON_EXTENSIONS + .contains(&extension.as_str()) + .then(|| path.to_string()) +} + +pub fn icon_url(icon_path: &str) -> String { + format!("{ICON_BASE}{icon_path}") +} + +/// A flat file name for the on-disk cache. Providers that share an icon +/// share a cache file. +pub fn cache_file_name(icon_path: &str) -> String { + icon_path.trim_start_matches('/').replace('/', "_") +} + +/// Works out the image type from its first bytes. The file extension and +/// the server's content type are not trusted. +pub fn sniff_mime(bytes: &[u8]) -> Option<&'static str> { + if bytes.starts_with(b"\x89PNG\r\n\x1a\n") { + return Some("image/png"); + } + if bytes.starts_with(&[0, 0, 1, 0]) { + return Some("image/x-icon"); + } + if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) { + return Some("image/jpeg"); + } + if bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WEBP" { + return Some("image/webp"); + } + // SVG is text. Look for the root element near the start. + let head = String::from_utf8_lossy(&bytes[..bytes.len().min(1024)]).to_ascii_lowercase(); + if head.contains(" String { + format!( + "data:{mime};base64,{}", + base64::engine::general_purpose::STANDARD.encode(bytes) + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + const SAMPLE: &str = r#"[ + { "id": "cloud", "name": "Cloud", "providers": [ + { "name": "Amazon Web Services", "href": "https://aws-provider.stackql.io/", + "icon": "/img/providers/aws/favicon.ico" }, + { "name": "AWS Cloud Control", "href": "https://awscc-provider.stackql.io/", + "icon": "/img/providers/aws/favicon.ico" }, + { "name": "Azure Stack", "href": "https://azure-stack-provider.stackql.io/", + "icon": "/img/providers/azure/favicon.ico" } + ]}, + { "id": "data", "name": "Data", "providers": [ + { "name": "Databricks Account", "registryAliases": ["databricks"], + "href": "https://databricks-account-provider.stackql.io/", + "icon": "/img/providers/databricks/favicon.ico" }, + { "name": "Microsoft Entra ID", "href": "https://entra-id-provider.stackql.io/", + "icon": "/img/providers/entra_id/entra_id_icon.svg" }, + { "name": "GitHub", "href": "https://github-provider.stackql.io/", + "icon": "/img/providers/github/favicon.ico", "invertOnDark": true }, + { "name": "Elsewhere", "href": "https://elsewhere-provider.stackql.io/", + "icon": "https://example.com/logo.png" } + ]} + ]"#; + + #[test] + fn the_provider_name_comes_from_the_documentation_address() { + let dir = Directory::parse(SAMPLE).unwrap(); + assert_eq!( + dir.lookup("aws").unwrap().display_name, + "Amazon Web Services" + ); + assert_eq!( + dir.lookup("awscc").unwrap().display_name, + "AWS Cloud Control" + ); + assert_eq!( + dir.lookup("azure_stack").unwrap().display_name, + "Azure Stack" + ); + assert_eq!( + dir.lookup("entra_id").unwrap().display_name, + "Microsoft Entra ID" + ); + assert_eq!( + dir.lookup("databricks_account").unwrap().icon_path, + "/img/providers/databricks/favicon.ico" + ); + } + + #[test] + fn registry_aliases_resolve_too() { + let dir = Directory::parse(SAMPLE).unwrap(); + assert_eq!( + dir.lookup("databricks").unwrap().display_name, + "Databricks Account" + ); + } + + #[test] + fn lookup_ignores_case_and_hyphen_style() { + let dir = Directory::parse(SAMPLE).unwrap(); + assert!(dir.lookup("GitHub").is_some()); + assert!(dir.lookup("azure-stack").is_some()); + assert!(dir.lookup(" aws ").is_some()); + } + + #[test] + fn the_icon_folder_fills_gaps_without_overriding() { + let dir = Directory::parse(SAMPLE).unwrap(); + // No documentation address says "azure", but the icon folder does. + assert_eq!(dir.lookup("azure").unwrap().display_name, "Azure Stack"); + // "aws" has its own entry, which the shared folder must not replace. + assert_eq!( + dir.lookup("aws").unwrap().display_name, + "Amazon Web Services" + ); + } + + #[test] + fn invert_on_dark_is_carried() { + let dir = Directory::parse(SAMPLE).unwrap(); + assert!(dir.lookup("github").unwrap().invert_on_dark); + assert!(!dir.lookup("aws").unwrap().invert_on_dark); + } + + #[test] + fn unknown_providers_and_unsafe_entries_have_no_icon() { + let dir = Directory::parse(SAMPLE).unwrap(); + assert!(dir.lookup("stackql_preview").is_none()); + // Its icon was a full URL to another site, so the entry was skipped. + assert!(dir.lookup("elsewhere").is_none()); + } + + #[test] + fn rubbish_is_an_error_not_an_empty_directory() { + assert!(Directory::parse("{}").is_err()); + assert!(Directory::parse("[]").is_err()); + assert!(Directory::parse("not json").is_err()); + } + + #[test] + fn the_bundled_snapshot_parses_and_knows_common_providers() { + let dir = Directory::parse(SNAPSHOT).unwrap(); + assert!(dir.len() >= 30, "only {} providers", dir.len()); + for provider in [ + "aws", "google", "azure", "github", "homebrew", "k8s", "okta", + ] { + assert!(dir.lookup(provider).is_some(), "{provider} missing"); + } + assert!(dir.lookup("openai_admin").unwrap().invert_on_dark); + } + + #[test] + fn only_plain_image_paths_on_the_icon_site_are_accepted() { + assert_eq!( + safe_icon_path("/img/providers/aws/favicon.ico").as_deref(), + Some("/img/providers/aws/favicon.ico") + ); + assert!(safe_icon_path("/img/providers/entra_id/entra_id_icon.svg").is_some()); + for bad in [ + "", + "https://example.com/x.png", + "//example.com/x.png", + "/img/../secret.png", + "/img/providers/aws/favicon.ico?x=1", + "/img/providers/aws/run.exe", + "/other/aws/favicon.ico", + "/img/providers/a b/favicon.ico", + "/img//example.com/x.png", + ] { + assert_eq!(safe_icon_path(bad), None, "{bad:?} should be refused"); + } + } + + #[test] + fn icon_urls_and_cache_names() { + assert_eq!( + icon_url("/img/providers/aws/favicon.ico"), + "https://stackql.io/img/providers/aws/favicon.ico" + ); + assert_eq!( + cache_file_name("/img/providers/aws/favicon.ico"), + "img_providers_aws_favicon.ico" + ); + } + + #[test] + fn image_types_are_recognised_from_content() { + assert_eq!(sniff_mime(b"\x89PNG\r\n\x1a\nrest"), Some("image/png")); + assert_eq!(sniff_mime(&[0, 0, 1, 0, 3, 0]), Some("image/x-icon")); + assert_eq!(sniff_mime(&[0xFF, 0xD8, 0xFF, 0xE0]), Some("image/jpeg")); + assert_eq!(sniff_mime(b"RIFF\0\0\0\0WEBPVP8 "), Some("image/webp")); + assert_eq!( + sniff_mime(b"\n"), + Some("image/svg+xml") + ); + assert_eq!(sniff_mime(b"not found"), None); + assert_eq!(sniff_mime(b""), None); + } + + #[test] + fn data_urls_are_base64() { + assert_eq!(data_url("image/png", b"hi!"), "data:image/png;base64,aGkh"); + } +} diff --git a/src-tauri/src/icons/mod.rs b/src-tauri/src/icons/mod.rs new file mode 100644 index 0000000..f11237e --- /dev/null +++ b/src-tauri/src/icons/mod.rs @@ -0,0 +1,380 @@ +//! Provider icons for the explorer. +//! +//! The webview makes no network calls of its own. The host looks a provider +//! up in the dictionary published by stackql.io, fetches its icon from that +//! site, keeps it in the app cache directory and hands it to the webview as +//! a `data:` URL. A provider with no entry, or whose icon cannot be fetched, +//! has no icon and the explorer falls back to its letter badge. Providers +//! built into the engine, such as `stackql_preview`, show StackQL's own icon, +//! which is compiled in. +//! +//! Only two hosts are ever contacted: the one that publishes the dictionary +//! and the icon site. Icon paths from the dictionary are checked before use. + +pub mod directory; + +use std::collections::HashMap; +use std::path::{Path, PathBuf}; +use std::sync::Mutex; +use std::time::{Duration, SystemTime}; + +use serde::Serialize; +use tokio::sync::OnceCell; + +use self::directory::{Directory, Entry}; +use crate::util::lock; + +/// How long a downloaded copy of the dictionary is used before it is +/// fetched again. +const DICTIONARY_MAX_AGE: Duration = Duration::from_secs(24 * 60 * 60); +/// How long a cached icon is used before it is fetched again. +const ICON_MAX_AGE: Duration = Duration::from_secs(30 * 24 * 60 * 60); +const MAX_ICON_BYTES: usize = 512 * 1024; +const MAX_DICTIONARY_BYTES: usize = 1024 * 1024; +const REQUEST_TIMEOUT: Duration = Duration::from_secs(8); + +/// StackQL's own icon, compiled in. Shown for the providers that are built +/// into the engine, which the published dictionary does not list. +const STACKQL_ICON: &[u8] = include_bytes!("../../icons/64x64.png"); + +/// The icon for a provider that is part of the engine itself, such as +/// `stackql_preview`. +fn built_in_icon(key: &str) -> Option { + let built_in = key == "stackql" || key.starts_with("stackql_"); + built_in.then(|| ProviderIcon { + data_url: directory::data_url("image/png", STACKQL_ICON), + invert_on_dark: false, + display_name: "StackQL".to_string(), + }) +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct ProviderIcon { + /// The image as a `data:` URL. + pub data_url: String, + /// The icon is dark on a transparent background. + pub invert_on_dark: bool, + /// The provider's display name, for example "Amazon Web Services". + pub display_name: String, +} + +pub struct ProviderIcons { + http: Option, + cache_dir: PathBuf, + directory: OnceCell, + /// Answers already worked out in this session, including "no icon". + resolved: Mutex>>, +} + +impl ProviderIcons { + pub fn new(cache_dir: PathBuf) -> Self { + let http = reqwest::Client::builder() + .timeout(REQUEST_TIMEOUT) + .connect_timeout(Duration::from_secs(5)) + .https_only(true) + .redirect(reqwest::redirect::Policy::limited(3)) + .user_agent(concat!("stackql-workbench/", env!("CARGO_PKG_VERSION"))) + .build() + .ok(); + Self { + http, + cache_dir, + directory: OnceCell::new(), + resolved: Mutex::new(HashMap::new()), + } + } + + /// A service that never touches the network. It answers from the cache + /// directory and the bundled dictionary only. + pub fn offline(cache_dir: PathBuf) -> Self { + Self { + http: None, + cache_dir, + directory: OnceCell::new(), + resolved: Mutex::new(HashMap::new()), + } + } + + /// Icons for the given providers. Providers without an icon are left out. + pub async fn icons(&self, providers: &[String]) -> HashMap { + let lookups = providers + .iter() + .map(|name| async move { self.icon(name).await.map(|icon| (name.clone(), icon)) }); + futures_util::future::join_all(lookups) + .await + .into_iter() + .flatten() + .collect() + } + + /// The icon for one provider, or `None` when there is none to show. + pub async fn icon(&self, provider: &str) -> Option { + let key = directory::normalise(provider); + if let Some(known) = lock(&self.resolved).get(&key) { + return known.clone(); + } + let icon = self.resolve(&key).await; + lock(&self.resolved).insert(key, icon.clone()); + icon + } + + async fn resolve(&self, key: &str) -> Option { + // The published dictionary wins if it ever lists a built-in provider. + match self.dictionary_icon(key).await { + Some(icon) => Some(icon), + None => built_in_icon(key), + } + } + + async fn dictionary_icon(&self, key: &str) -> Option { + let entry = self.directory().await.lookup(key)?.clone(); + let bytes = self.icon_bytes(&entry).await?; + let mime = directory::sniff_mime(&bytes)?; + Some(ProviderIcon { + data_url: directory::data_url(mime, &bytes), + invert_on_dark: entry.invert_on_dark, + display_name: entry.display_name, + }) + } + + async fn directory(&self) -> &Directory { + self.directory + .get_or_init(|| async { self.load_directory().await }) + .await + } + + /// The freshest dictionary available: a recent download, then a new + /// download, then an old download, then the copy built into the app. + async fn load_directory(&self) -> Directory { + let path = self.cache_dir.join("providers.json"); + let cached = read_cached(&path); + + if let Some((text, age)) = &cached + && *age < DICTIONARY_MAX_AGE + && let Ok(parsed) = Directory::parse(text) + { + return parsed; + } + + if let Some(bytes) = self + .fetch(directory::DICTIONARY_URL, MAX_DICTIONARY_BYTES) + .await + && let Ok(text) = String::from_utf8(bytes) + && let Ok(parsed) = Directory::parse(&text) + { + write_cache(&path, text.as_bytes()); + return parsed; + } + + if let Some((text, _)) = &cached + && let Ok(parsed) = Directory::parse(text) + { + return parsed; + } + + Directory::parse(directory::SNAPSHOT).unwrap_or_default() + } + + async fn icon_bytes(&self, entry: &Entry) -> Option> { + let path = self + .cache_dir + .join("icons") + .join(directory::cache_file_name(&entry.icon_path)); + + let cached = std::fs::read(&path).ok().filter(|b| is_image(b)); + if let Some(bytes) = &cached + && file_age(&path).is_some_and(|age| age < ICON_MAX_AGE) + { + return Some(bytes.clone()); + } + + let url = directory::icon_url(&entry.icon_path); + match self + .fetch(&url, MAX_ICON_BYTES) + .await + .filter(|b| is_image(b)) + { + Some(bytes) => { + write_cache(&path, &bytes); + Some(bytes) + } + // An old copy is better than the letter badge. + None => cached, + } + } + + /// Fetches a URL, giving up on anything that is not a success or is + /// larger than `limit`. + async fn fetch(&self, url: &str, limit: usize) -> Option> { + let http = self.http.as_ref()?; + let response = http.get(url).send().await.ok()?; + if !response.status().is_success() { + return None; + } + if response + .content_length() + .is_some_and(|length| length > limit as u64) + { + return None; + } + let bytes = response.bytes().await.ok()?; + (bytes.len() <= limit).then(|| bytes.to_vec()) + } +} + +fn is_image(bytes: &[u8]) -> bool { + directory::sniff_mime(bytes).is_some() +} + +fn file_age(path: &Path) -> Option { + let modified = std::fs::metadata(path).ok()?.modified().ok()?; + SystemTime::now().duration_since(modified).ok() +} + +fn read_cached(path: &Path) -> Option<(String, Duration)> { + let text = std::fs::read_to_string(path).ok()?; + Some((text, file_age(path)?)) +} + +/// The cache is a convenience. A failed write is not worth reporting. +fn write_cache(path: &Path, bytes: &[u8]) { + if let Some(dir) = path.parent() { + let _ = std::fs::create_dir_all(dir); + } + let _ = std::fs::write(path, bytes); +} + +#[cfg(test)] +mod tests { + use super::*; + + const PNG: &[u8] = b"\x89PNG\r\n\x1a\nnot-really-pixels"; + + fn cache(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("wb-icons-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("icons")).unwrap(); + dir + } + + #[tokio::test] + async fn a_cached_icon_is_served_without_the_network() { + let dir = cache("hit"); + std::fs::write(dir.join("icons").join("img_providers_aws_favicon.ico"), PNG).unwrap(); + let icons = ProviderIcons::offline(dir.clone()); + + let icon = icons.icon("aws").await.expect("cached icon"); + assert!(icon.data_url.starts_with("data:image/png;base64,")); + assert_eq!(icon.display_name, "Amazon Web Services"); + assert!(!icon.invert_on_dark); + + // awscc shares the same icon file in the dictionary. + assert!(icons.icon("awscc").await.is_some()); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn a_provider_without_an_entry_has_no_icon() { + let dir = cache("unknown"); + let icons = ProviderIcons::offline(dir.clone()); + assert_eq!(icons.icon("no_such_provider").await, None); + // Not a built-in just because the name mentions stackql somewhere. + assert_eq!(icons.icon("my_stackql_thing").await, None); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn built_in_providers_show_the_stackql_icon_without_the_network() { + let dir = cache("builtin"); + let icons = ProviderIcons::offline(dir.clone()); + + let icon = icons.icon("stackql_preview").await.expect("built-in icon"); + assert!(icon.data_url.starts_with("data:image/png;base64,")); + assert_eq!(icon.display_name, "StackQL"); + assert!(!icon.invert_on_dark); + // The compiled-in file really is an image. + assert_eq!(directory::sniff_mime(STACKQL_ICON), Some("image/png")); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn an_icon_that_cannot_be_fetched_falls_back_to_none() { + // In the dictionary, nothing in the cache, and no network. + let dir = cache("miss"); + let icons = ProviderIcons::offline(dir.clone()); + assert_eq!(icons.icon("github").await, None); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn a_cached_file_that_is_not_an_image_is_ignored() { + let dir = cache("corrupt"); + std::fs::write( + dir.join("icons").join("img_providers_aws_favicon.ico"), + b"404", + ) + .unwrap(); + let icons = ProviderIcons::offline(dir.clone()); + assert_eq!(icons.icon("aws").await, None); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn a_downloaded_dictionary_in_the_cache_is_preferred_to_the_snapshot() { + let dir = cache("dictionary"); + std::fs::write( + dir.join("providers.json"), + r#"[{ "providers": [{ "name": "Brand New", "href": "https://brandnew-provider.stackql.io/", "icon": "/img/providers/brandnew/favicon.png" }] }]"#, + ) + .unwrap(); + std::fs::write( + dir.join("icons").join("img_providers_brandnew_favicon.png"), + PNG, + ) + .unwrap(); + let icons = ProviderIcons::offline(dir.clone()); + + assert_eq!( + icons.icon("brandnew").await.unwrap().display_name, + "Brand New" + ); + // The snapshot was not consulted, so a provider only it knows is absent. + assert_eq!(icons.icon("aws").await, None); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn icons_returns_only_the_providers_that_have_one() { + let dir = cache("batch"); + std::fs::write(dir.join("icons").join("img_providers_aws_favicon.ico"), PNG).unwrap(); + let icons = ProviderIcons::offline(dir.clone()); + + let found = icons + .icons(&[ + "aws".to_string(), + "no_such_provider".to_string(), + "github".to_string(), + ]) + .await; + assert_eq!(found.keys().collect::>(), vec!["aws"]); + let _ = std::fs::remove_dir_all(dir); + } + + #[test] + fn the_icon_serialises_in_camel_case() { + let icon = ProviderIcon { + data_url: "data:image/png;base64,AA==".into(), + invert_on_dark: true, + display_name: "GitHub".into(), + }; + assert_eq!( + serde_json::to_value(icon).unwrap(), + serde_json::json!({ + "dataUrl": "data:image/png;base64,AA==", + "invertOnDark": true, + "displayName": "GitHub" + }) + ); + } +} diff --git a/src-tauri/src/icons/providers.snapshot.json b/src-tauri/src/icons/providers.snapshot.json new file mode 100644 index 0000000..cd26e6e --- /dev/null +++ b/src-tauri/src/icons/providers.snapshot.json @@ -0,0 +1,405 @@ +[ + { + "id": "cloud-providers", + "name": "Cloud Providers", + "providers": [ + { + "name": "Amazon Web Services", + "href": "https://aws-provider.stackql.io/", + "icon": "/img/providers/aws/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-aws", + "branch": "stackql-provider" + }, + { + "name": "Microsoft Azure", + "href": "https://azure-provider.stackql.io/", + "icon": "/img/providers/azure/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-azure", + "branch": "stackql-provider" + }, + { + "name": "Google Cloud Platform", + "href": "https://google-provider.stackql.io/", + "icon": "/img/providers/google/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-google", + "branch": "main" + }, + { + "name": "Oracle Cloud Infrastructure", + "href": "https://oci-provider.stackql.io/", + "icon": "/img/providers/oci/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-oci", + "branch": "main" + }, + { + "name": "Digital Ocean", + "href": "https://digitalocean-provider.stackql.io/", + "icon": "/img/providers/digitalocean/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-digitalocean", + "branch": "main" + }, + { + "name": "Cloudflare", + "href": "https://cloudflare-provider.stackql.io/", + "icon": "/img/providers/cloudflare/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-cloudflare", + "branch": "stackql-provider" + }, + { + "name": "Linode", + "href": "https://linode-provider.stackql.io/", + "icon": "/img/providers/linode/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-linode", + "branch": "main" + }, + { + "name": "OVHcloud", + "href": "https://ovh-provider.stackql.io/", + "icon": "/img/providers/ovh/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-ovh", + "branch": "main" + }, + { + "name": "AWS Cloud Control", + "href": "https://awscc-provider.stackql.io/", + "icon": "/img/providers/aws/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-awscc", + "branch": "main" + }, + { + "name": "Azure Stack", + "href": "https://azure-stack-provider.stackql.io/", + "icon": "/img/providers/azure/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-azure", + "branch": "stackql-provider" + }, + { + "name": "Azure ISV", + "href": "https://azure-isv-provider.stackql.io/", + "icon": "/img/providers/azure/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-azure", + "branch": "stackql-provider" + } + ] + }, + { + "id": "data-analytics", + "name": "Data & Analytics", + "providers": [ + { + "name": "Databricks Account", + "registryAliases": [ + "databricks" + ], + "href": "https://databricks-account-provider.stackql.io/", + "icon": "/img/providers/databricks/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-databricks", + "branch": "stackql-provider" + }, + { + "name": "Databricks Workspace", + "href": "https://databricks-workspace-provider.stackql.io/", + "icon": "/img/providers/databricks/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-databricks", + "branch": "stackql-provider" + }, + { + "name": "Snowflake", + "href": "https://snowflake-provider.stackql.io/", + "icon": "/img/providers/snowflake/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-snowflake", + "branch": "stackql-provider" + }, + { + "name": "ClickHouse", + "href": "https://clickhouse-provider.stackql.io/", + "icon": "/img/providers/clickhouse/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-clickhouse", + "branch": "main" + }, + { + "name": "Fivetran", + "href": "https://fivetran-provider.stackql.io/", + "icon": "/img/providers/fivetran/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-fivetran", + "branch": "main" + }, + { + "name": "Confluent", + "href": "https://confluent-provider.stackql.io/", + "icon": "/img/providers/confluent/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-confluent", + "branch": "main" + }, + { + "name": "Kafka", + "href": "https://kafka-provider.stackql.io/", + "icon": "/img/providers/kafka/kafka.png", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-confluent", + "branch": "main", + "invertOnDark": true + } + ] + }, + { + "id": "identity-security", + "name": "Identity & Security", + "providers": [ + { + "name": "Okta", + "href": "https://okta-provider.stackql.io/", + "icon": "/img/providers/okta/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-okta", + "branch": "main", + "invertOnDark": true + }, + { + "name": "Google Admin", + "href": "https://googleadmin-provider.stackql.io/", + "icon": "/img/providers/googleadmin/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-google", + "branch": "main" + }, + { + "name": "Microsoft Entra ID", + "href": "https://entra-id-provider.stackql.io/", + "icon": "/img/providers/entra_id/entra_id_icon.svg", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-entraid", + "branch": "stackql-provider" + } + ] + }, + { + "id": "ai-machine-learning", + "name": "AI & Machine Learning", + "providers": [ + { + "name": "OpenAI", + "href": "https://openai-provider.stackql.io/", + "icon": "/img/providers/openai/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-openai", + "branch": "main", + "invertOnDark": true + }, + { + "name": "OpenAI Admin", + "href": "https://openai-admin-provider.stackql.io/", + "icon": "/img/providers/openai/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-openai-admin", + "branch": "main", + "invertOnDark": true + }, + { + "name": "Anthropic", + "href": "https://anthropic-provider.stackql.io/", + "icon": "/img/providers/anthropic/favicon.png", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-anthropic", + "branch": "main" + }, + { + "name": "Anthropic Admin", + "href": "https://anthropic-admin-provider.stackql.io/", + "icon": "/img/providers/anthropic/favicon.png", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-anthropic", + "branch": "main" + }, + { + "name": "Google Gemini", + "href": "https://gemeni-provider.stackql.io/", + "icon": "/img/providers/gemeni/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-gemeni", + "branch": "main" + }, + { + "name": "TypeSafe AI", + "href": "https://typesafe-provider.stackql.io/", + "icon": "/img/providers/typesafe/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-typesafe", + "branch": "main" + }, + { + "name": "NVIDIA NGC", + "href": "https://nvidia-provider.stackql.io/", + "icon": "/img/providers/nvidia/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-nvidia", + "branch": "main" + } + ] + }, + { + "id": "devops-development", + "name": "DevOps & Development", + "providers": [ + { + "name": "GitHub", + "href": "https://github-provider.stackql.io/", + "icon": "/img/providers/github/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-github", + "branch": "main", + "invertOnDark": true + }, + { + "name": "Kubernetes", + "href": "https://k8s-provider.stackql.io/", + "icon": "/img/providers/k8s/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-k8s", + "branch": "main" + }, + { + "name": "GitLab", + "href": "https://gitlab-provider.stackql.io/", + "icon": "/img/providers/gitlab/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-gitlab", + "branch": "main" + }, + { + "name": "Firebase", + "href": "https://firebase-provider.stackql.io/", + "icon": "/img/providers/firebase/favicon.png", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-google", + "branch": "main" + }, + { + "name": "Railway", + "href": "https://railway-provider.stackql.io/", + "icon": "/img/providers/railway/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-railway", + "branch": "main", + "invertOnDark": true + }, + { + "name": "Vercel", + "href": "https://vercel-provider.stackql.io/", + "icon": "/img/providers/vercel/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-vercel", + "branch": "main" + }, + { + "name": "Netlify", + "href": "https://netlify-provider.stackql.io/", + "icon": "/img/providers/netlify/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-netlify", + "branch": "main" + }, + { + "name": "Deno Deploy", + "href": "https://deno-provider.stackql.io/", + "icon": "/img/providers/deno/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-deno", + "branch": "main" + }, + { + "name": "Supabase", + "href": "https://supabase-provider.stackql.io/", + "icon": "/img/providers/supabase/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-supabase", + "branch": "main" + } + ] + }, + { + "id": "monitoring-observability", + "name": "Monitoring & Observability", + "providers": [ + { + "name": "DataDog", + "href": "https://datadog-provider.stackql.io/", + "icon": "/img/providers/datadog/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-datadog", + "branch": "main" + }, + { + "name": "SumoLogic", + "href": "https://sumologic-provider.stackql.io/", + "icon": "/img/providers/sumologic/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-sumologic", + "branch": "main" + }, + { + "name": "PagerDuty", + "href": "https://pagerduty-provider.stackql.io/", + "icon": "/img/providers/pagerduty/icon.svg", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-pagerduty", + "branch": "main" + } + ] + }, + { + "id": "other-providers", + "name": "Other Providers", + "providers": [ + { + "name": "Google Workspace", + "href": "https://googleworkspace-provider.stackql.io/", + "icon": "/img/providers/googleworkspace/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-google", + "branch": "main" + }, + { + "name": "GoDaddy", + "href": "https://godaddy-provider.stackql.io/", + "icon": "/img/providers/godaddy/favicon.png", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-godaddy", + "branch": "main" + }, + { + "name": "Azure Extras", + "href": "https://azure-extras-provider.stackql.io/", + "icon": "/img/providers/azure/favicon.ico", + "deployedBy": "netlify", + "repo": "stackql-registry/stackql-provider-azure", + "branch": "stackql-provider" + }, + { + "name": "Homebrew", + "href": "https://homebrew-provider.stackql.io/", + "icon": "/img/providers/homebrew/favicon.ico", + "deployedBy": "github", + "repo": "stackql-registry/stackql-provider-homebrew", + "branch": "main" + } + ] + } +] diff --git a/src-tauri/src/ipc/links.rs b/src-tauri/src/ipc/links.rs new file mode 100644 index 0000000..0de297c --- /dev/null +++ b/src-tauri/src/ipc/links.rs @@ -0,0 +1,78 @@ +//! Opening the app's own links in the operator's browser. +//! +//! The webview names a link. It never supplies an address, so nothing a +//! model writes, and nothing else on a page, can be opened this way. + +use serde::Deserialize; +use tauri::State; +use tauri_plugin_opener::OpenerExt; + +use super::AppState; +use crate::error::{HostError, HostResult}; + +/// The links the Help menu offers. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum Link { + Docs, + QueryLibrary, + Issues, +} + +impl Link { + pub const ALL: [Self; 3] = [Self::Docs, Self::QueryLibrary, Self::Issues]; + + pub fn url(self) -> &'static str { + match self { + Self::Docs => "https://stackql.io/docs", + Self::QueryLibrary => "https://stackql.io/docs/query-library", + Self::Issues => "https://github.com/stackql/stackql-workbench/issues", + } + } +} + +/// Opens one of the app's links in the default browser. +#[tauri::command] +pub fn open_link(app: tauri::AppHandle, link: Link) -> HostResult<()> { + app.opener() + .open_url(link.url(), None::<&str>) + .map_err(|err| HostError::Internal(format!("Could not open {}: {err}", link.url()))) +} + +/// Shows the app's log file for this run in the system's file manager. +/// The host holds the path. The webview names nothing, and is told nothing +/// but the path that was shown. +#[tauri::command] +pub fn reveal_log(app: tauri::AppHandle, state: State<'_, AppState>) -> HostResult { + let path = state.log.path().ok_or_else(|| { + HostError::Internal("No log is being kept, because its folder could not be created.".into()) + })?; + app.opener() + .reveal_item_in_dir(path) + .map_err(|err| HostError::Internal(format!("Could not show {}: {err}", path.display())))?; + Ok(path.display().to_string()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn every_link_is_an_https_address_of_the_project() { + for link in Link::ALL { + let url = link.url(); + assert!( + url.starts_with("https://stackql.io/") + || url.starts_with("https://github.com/stackql/"), + "{url}" + ); + } + } + + #[test] + fn a_link_is_named_not_given_as_an_address() { + let link: Link = serde_json::from_str("\"queryLibrary\"").unwrap(); + assert_eq!(link, Link::QueryLibrary); + assert!(serde_json::from_str::("\"https://example.com\"").is_err()); + } +} diff --git a/src-tauri/src/ipc/mod.rs b/src-tauri/src/ipc/mod.rs new file mode 100644 index 0000000..0ffe786 --- /dev/null +++ b/src-tauri/src/ipc/mod.rs @@ -0,0 +1,587 @@ +//! Typed IPC: the commands the webview can call and the events it can hear. +//! +//! This is the whole surface between the webview and the host. The webview +//! side is `src/host/`, the only place in the webview that touches Tauri. + +pub mod links; +pub mod save; + +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; + +use tauri::State; +use tauri::ipc::Channel; + +use crate::activity::{Activity, History, HistoryEntry, read_audit}; +use crate::agent::approvals::ApprovalDecision; +use crate::agent::backend::BackendKind; +use crate::agent::backends; +use crate::agent::runtime::{ + AgentEvent, AgentRuntime, DelegateInfo, DelegateRequest, Emit, TurnSummary, +}; +use crate::agent::turnlog::TurnLog; +use crate::applog::AppLog; +use crate::config::{InferenceSettings, Settings, SettingsStore}; +use crate::connection::{Connection, EngineStatus, EventSink, SafetyMode}; +use crate::error::{HostError, HostResult}; +use crate::icons::{ProviderIcon, ProviderIcons}; +use crate::library::{Library, LibraryDocument, LibraryIndex}; +use crate::query::explorer::{self, Field, Method, MethodField, Provider, Resource, Service}; +use crate::query::result::{QueryEvent, RunSummary}; +use crate::secrets::SecretStore; +use crate::util::lock; + +/// Emitted whenever the engine status changes. The payload is `EngineStatus`. +pub const ENGINE_STATUS_EVENT: &str = "engine-status"; + +pub struct AppState { + pub connection: Arc, + pub settings: Arc, + pub icons: Arc, + pub library: Arc, + pub agent: Arc, + pub secrets: Arc, + /// False when the OS keychain could not be opened and keys are held in + /// memory for this run only. + pub keychain_available: bool, + pub history: Arc, + /// The app's own log for this run. + pub log: Arc, +} + +#[derive(Debug, Clone, serde::Serialize)] +#[serde(rename_all = "camelCase")] +pub struct SettingsView { + pub settings: Settings, + /// Set when the settings file could not be read at startup. + pub warning: Option, +} + +#[tauri::command] +pub async fn engine_status(state: State<'_, AppState>) -> HostResult { + Ok(state.connection.status()) +} + +#[tauri::command] +pub async fn engine_restart(state: State<'_, AppState>) -> HostResult { + Ok(state.connection.restart().await) +} + +#[tauri::command] +pub async fn settings_get(state: State<'_, AppState>) -> HostResult { + Ok(SettingsView { + settings: state.settings.get(), + warning: state.settings.load_warning().map(str::to_string), + }) +} + +/// Saves the engine settings. If one of them changed, the engine is +/// restarted so the change takes effect. Chat settings are not touched here. +/// They have their own commands, because they come with a secret. +#[tauri::command] +pub async fn settings_save(state: State<'_, AppState>, settings: Settings) -> HostResult { + let before = state.settings.get(); + let saved = state.settings.replace(Settings { + engine_path: settings.engine_path, + env_file: settings.env_file, + approot: settings.approot, + ..before.clone() + })?; + if before.engine_path != saved.engine_path + || before.env_file != saved.env_file + || before.approot != saved.approot + { + state.connection.restart().await; + } + Ok(saved) +} + +/// Runs the statements in `sql` on the operator's session. Events stream +/// over `on_event` while the command is pending. The command resolves when +/// the run ends. +#[tauri::command] +pub async fn query_run( + state: State<'_, AppState>, + run_id: String, + sql: String, + on_event: Channel, +) -> HostResult { + let recorder = Arc::new(HistoryRecorder::new(state.history.clone())); + let recording = recorder.clone(); + let sink: EventSink = Box::new(move |event| { + recording.observe(&event); + // A send only fails when the webview has gone away. + let _ = on_event.send(event); + }); + let summary = state.connection.run(run_id, sql, sink).await?; + if summary.abandoned { + recorder.abandoned(); + } + Ok(summary) +} + +/// Writes each statement of a run to the operator's history as it ends. +struct HistoryRecorder { + history: Arc, + /// Statements that have started and not yet ended. + open: Mutex>, +} + +impl HistoryRecorder { + fn new(history: Arc) -> Self { + Self { + history, + open: Mutex::new(HashMap::new()), + } + } + + fn observe(&self, event: &QueryEvent) { + match event { + QueryEvent::StatementStarted { index, sql, .. } => { + lock(&self.open).insert(*index, sql.clone()); + } + QueryEvent::StatementFinished { + index, + row_count, + elapsed_ms, + } => { + if let Some(sql) = lock(&self.open).remove(index) { + self.history.record(&HistoryEntry::now( + sql, + "ok", + Some(*row_count), + *elapsed_ms, + )); + } + } + QueryEvent::StatementFailed { + index, + error, + elapsed_ms, + } => { + if let Some(sql) = lock(&self.open).remove(index) { + self.history.record( + &HistoryEntry::now(sql, "error", None, *elapsed_ms) + .with_error(error.message.clone()), + ); + } + } + _ => {} + } + } + + /// The operator stopped waiting. Whatever was running is on record as + /// abandoned, since the engine may still complete it. + fn abandoned(&self) { + for (_, sql) in lock(&self.open).drain() { + self.history + .record(&HistoryEntry::now(sql, "abandoned", None, 0)); + } + } +} + +/// Stops waiting for a run. The engine has no cancel, so the statement may +/// still complete there. +#[tauri::command] +pub async fn query_abandon(state: State<'_, AppState>, run_id: String) -> HostResult { + Ok(state.connection.abandon(&run_id)) +} + +/// Puts text on the system clipboard. Write only: the webview cannot read +/// the clipboard through the host. +/// +/// Not async, so it runs on the main thread, which is where macOS expects +/// pasteboard access. +#[tauri::command] +pub fn clipboard_write_text(text: String) -> HostResult<()> { + let mut clipboard = arboard::Clipboard::new() + .map_err(|err| HostError::Internal(format!("Could not open the clipboard: {err}")))?; + clipboard + .set_text(text) + .map_err(|err| HostError::Internal(format!("Could not copy to the clipboard: {err}"))) +} + +/// Icons for the named providers, as `data:` URLs. Providers without an icon +/// are left out, and the explorer shows its letter badge for them. +#[tauri::command] +pub async fn provider_icons( + state: State<'_, AppState>, + providers: Vec, +) -> HostResult> { + Ok(state.icons.icons(&providers).await) +} + +/// The query library's index. The host fetches it, and keeps a copy for +/// when the library cannot be reached. +#[tauri::command] +pub async fn library_index( + state: State<'_, AppState>, + refresh: Option, +) -> HostResult { + state.library.index(refresh.unwrap_or(false)).await +} + +/// One entry of the query library: its text and its statement. +#[tauri::command] +pub async fn library_document( + state: State<'_, AppState>, + id: String, +) -> HostResult { + state.library.document(&id).await +} + +#[tauri::command] +pub async fn explorer_providers(state: State<'_, AppState>) -> HostResult> { + let result = state + .connection + .fetch(explorer::PROVIDERS_SQL.to_string()) + .await?; + // The tree leaves the provider built into the engine out for now. + Ok(explorer::visible_providers(explorer::map_providers( + &result, + )?)) +} + +/// What the registry offers. The engine asks the registry, so this needs +/// the network. It runs when the explorer loads and when the operator asks. +#[tauri::command] +pub async fn explorer_registry(state: State<'_, AppState>) -> HostResult> { + let result = state + .connection + .fetch(explorer::REGISTRY_LIST_SQL.to_string()) + .await?; + Ok(explorer::visible_providers(explorer::map_registry( + &result, + )?)) +} + +#[tauri::command] +pub async fn explorer_services( + state: State<'_, AppState>, + provider: String, +) -> HostResult> { + let sql = explorer::services_sql(&provider)?; + explorer::map_services(&state.connection.fetch(sql).await?) +} + +#[tauri::command] +pub async fn explorer_resources( + state: State<'_, AppState>, + provider: String, + service: String, +) -> HostResult> { + let sql = explorer::resources_sql(&provider, &service)?; + explorer::map_resources(&state.connection.fetch(sql).await?) +} + +#[tauri::command] +pub async fn explorer_methods( + state: State<'_, AppState>, + provider: String, + service: String, + resource: String, +) -> HostResult> { + let sql = explorer::methods_sql(&provider, &service, &resource)?; + explorer::map_methods(&state.connection.fetch(sql).await?) +} + +#[tauri::command] +pub async fn explorer_fields( + state: State<'_, AppState>, + provider: String, + service: String, + resource: String, +) -> HostResult> { + let sql = explorer::fields_sql(&provider, &service, &resource)?; + explorer::map_fields(&state.connection.fetch(sql).await?) +} + +#[tauri::command] +pub async fn explorer_method_fields( + state: State<'_, AppState>, + provider: String, + service: String, + resource: String, + method: String, +) -> HostResult> { + let sql = explorer::method_fields_sql(&provider, &service, &resource, &method)?; + explorer::map_method_fields(&state.connection.fetch(sql).await?) +} + +/// What the webview may know about the chat configuration. The API key is +/// never part of it, only whether one is stored. +#[derive(Debug, Clone, serde::Serialize)] +#[serde(rename_all = "camelCase")] +pub struct AgentConfigView { + /// `None` means chat is not configured and the chat pane stays hidden. + pub inference: Option, + pub has_key: bool, + pub safety_mode: SafetyMode, + pub backends: Vec, + /// False when keys cannot be kept in the OS keychain on this machine. + pub keychain_available: bool, +} + +/// One backend the operator can choose, with what it defaults to. +#[derive(Debug, Clone, serde::Serialize)] +#[serde(rename_all = "camelCase")] +pub struct BackendOption { + pub kind: BackendKind, + pub default_model: String, + pub default_base_url: String, + pub key_optional: bool, + /// An agent the operator installed runs the model. There is no key and + /// no address to enter, and no approval prompt. + pub delegated: bool, +} + +fn agent_config_view(state: &AppState) -> AgentConfigView { + let settings = state.settings.get(); + let has_key = settings.inference.as_ref().is_some_and(|inference| { + inference + .kind + .secret_name() + .is_some_and(|name| state.secrets.get(name).is_ok_and(|key| key.is_some())) + }); + let backends = BackendKind::ALL + .into_iter() + .map(|kind| BackendOption { + kind, + default_model: backends::default_model(kind).to_string(), + default_base_url: backends::default_base_url(kind).to_string(), + key_optional: kind.key_optional(), + delegated: kind.is_delegated(), + }) + .collect(); + AgentConfigView { + inference: settings.inference, + has_key, + safety_mode: settings.safety_mode, + backends, + keychain_available: state.keychain_available, + } +} + +#[tauri::command] +pub async fn agent_config_get(state: State<'_, AppState>) -> HostResult { + Ok(agent_config_view(&state)) +} + +/// Saves the chat backend. A key, when given, goes to the OS keychain and +/// nowhere else. Leaving it out keeps the key that is already stored. +#[tauri::command] +pub async fn agent_config_save( + state: State<'_, AppState>, + inference: InferenceSettings, + api_key: Option, +) -> HostResult { + if let Some(key) = api_key.as_deref().map(str::trim).filter(|k| !k.is_empty()) + && let Some(name) = inference.kind.secret_name() + { + state.secrets.set(name, key)?; + } + let current = state.settings.get(); + state.settings.replace(Settings { + inference: Some(inference), + ..current + })?; + // A different model should not inherit a conversation it did not have. + state.agent.reset().await; + Ok(agent_config_view(&state)) +} + +/// Removes the chat backend and its stored key. The chat pane goes away and +/// the rest of the app carries on as before. +#[tauri::command] +pub async fn agent_config_clear(state: State<'_, AppState>) -> HostResult { + let current = state.settings.get(); + if let Some(name) = current + .inference + .as_ref() + .and_then(|inference| inference.kind.secret_name()) + { + state.secrets.delete(name)?; + } + state.settings.replace(Settings { + inference: None, + ..current + })?; + state.agent.reset().await; + Ok(agent_config_view(&state)) +} + +/// Sets what the agent may do without asking. Takes effect on the next +/// message, when a new engine session is opened in that mode. +#[tauri::command] +pub async fn agent_set_safety_mode( + state: State<'_, AppState>, + mode: SafetyMode, +) -> HostResult { + let current = state.settings.get(); + let saved = state.settings.replace(Settings { + safety_mode: mode, + ..current + })?; + Ok(saved.safety_mode) +} + +/// Sends a message to the assistant. Events stream over `on_event` while +/// the command is pending. It resolves when the turn ends. +/// +/// What goes wrong on the way is also written to the app's log: a tool call +/// that failed, and a turn that did. The conversation does not list the +/// first, so the log is where it can be read. +#[tauri::command] +pub async fn agent_send( + state: State<'_, AppState>, + text: String, + on_event: Channel, +) -> HostResult { + let settings = state.settings.get(); + let inference = settings.inference.clone().ok_or_else(|| { + HostError::Agent("Chat is not configured. Choose a backend in Settings.".to_string()) + })?; + let turn_log = Arc::new(TurnLog::new( + state.log.clone(), + backend_name(inference.kind), + &inference.model, + settings.safety_mode, + )); + let observer = turn_log.clone(); + let emit: Emit = Arc::new(move |event| { + observer.observe(&event); + // A send only fails when the webview has gone away. + let _ = on_event.send(event); + }); + let outcome = run_turn(&state, &settings, inference, text, emit).await; + turn_log.finished(&outcome); + outcome +} + +/// The backend's name as settings spell it, for the log. +fn backend_name(kind: BackendKind) -> &'static str { + match kind { + BackendKind::Gemini => "gemini", + BackendKind::Anthropic => "anthropic", + BackendKind::OpenaiCompatible => "openai_compatible", + BackendKind::GithubCopilot => "github_copilot", + } +} + +async fn run_turn( + state: &AppState, + settings: &Settings, + inference: InferenceSettings, + text: String, + emit: Emit, +) -> HostResult { + if inference.kind.is_delegated() { + return state + .agent + .send_delegated( + delegate_request(&inference), + settings.safety_mode, + text, + emit, + ) + .await; + } + let key = match inference.kind.secret_name() { + Some(name) => state.secrets.get(name)?, + None => None, + }; + let backend = + backends::build(&inference, key).map_err(|err| HostError::Agent(err.to_string()))?; + state + .agent + .send(backend, settings.safety_mode, text, emit) + .await +} + +fn delegate_request(inference: &InferenceSettings) -> DelegateRequest { + DelegateRequest { + model: Some(inference.model.trim().to_string()).filter(|model| !model.is_empty()), + program: inference.program.as_deref().map(std::path::PathBuf::from), + subagents: inference.subagents, + } +} + +/// Asks a delegated agent for its version and the models it offers. This +/// starts the agent and opens a session, and sends no prompt. `program` is +/// the location in the settings form, which may not be saved yet. +#[tauri::command] +pub async fn agent_delegate_info( + state: State<'_, AppState>, + program: Option, +) -> HostResult { + let request = DelegateRequest { + model: None, + program: program + .map(|p| p.trim().trim_matches('"').to_string()) + .filter(|p| !p.is_empty()) + .map(std::path::PathBuf::from), + // Nothing is asked of the agent here, so it needs no subagents. + subagents: false, + }; + state + .agent + .delegate_info(request, state.settings.get().safety_mode) + .await +} + +/// Delivers the operator's answer to an approval prompt. +#[tauri::command] +pub async fn agent_approve( + state: State<'_, AppState>, + approval_id: String, + decision: ApprovalDecision, +) -> HostResult { + Ok(state.agent.approvals().resolve(&approval_id, decision)) +} + +/// Stops the turn that is running. A statement the engine has already +/// started is not interrupted. +#[tauri::command] +pub async fn agent_stop(state: State<'_, AppState>) -> HostResult { + Ok(state.agent.stop()) +} + +/// Starts a new conversation. +#[tauri::command] +pub async fn agent_reset(state: State<'_, AppState>) -> HostResult<()> { + state.agent.reset().await; + Ok(()) +} + +/// What was run recently, by the operator and by the agent. +#[tauri::command] +pub async fn activity_list( + state: State<'_, AppState>, + limit: Option, +) -> HostResult { + let limit = limit.unwrap_or(200).clamp(1, 2000); + let agent = state + .connection + .audit_dir() + .map(|dir| read_audit(&dir, limit)) + .unwrap_or_default(); + Ok(Activity { + operator: state.history.list(limit), + agent, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_log_names_a_backend_the_way_settings_do() { + for kind in BackendKind::ALL { + assert_eq!( + serde_json::to_value(kind).unwrap(), + serde_json::Value::String(backend_name(kind).to_string()) + ); + } + } +} diff --git a/src-tauri/src/ipc/save.rs b/src-tauri/src/ipc/save.rs new file mode 100644 index 0000000..d003cf3 --- /dev/null +++ b/src-tauri/src/ipc/save.rs @@ -0,0 +1,120 @@ +//! Saving text the operator exports. +//! +//! The webview hands over the text and a suggested name. Where it goes is +//! chosen by the operator in the system's save dialog, never by the webview. + +use std::path::Path; + +use serde::Deserialize; +use tauri_plugin_dialog::DialogExt; + +use crate::error::{HostError, HostResult}; + +/// What is being saved, which decides the file type offered in the dialog. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum SaveKind { + Csv, + Json, + Jsonl, +} + +impl SaveKind { + fn filter(self) -> (&'static str, &'static [&'static str]) { + match self { + Self::Csv => ("CSV", &["csv"]), + Self::Json => ("JSON", &["json"]), + Self::Jsonl => ("JSON Lines", &["jsonl"]), + } + } +} + +/// The last component of a suggested name, so a name from the webview can +/// never carry a folder with it. +fn file_name_only(suggested: &str) -> String { + Path::new(suggested) + .file_name() + .map(|name| name.to_string_lossy().into_owned()) + .filter(|name| !name.is_empty()) + .unwrap_or_else(|| "export".to_string()) +} + +fn write_text(path: &Path, contents: &str) -> HostResult<()> { + std::fs::write(path, contents) + .map_err(|err| HostError::Internal(format!("Could not save {}: {err}", path.display()))) +} + +/// Asks the operator where to save `contents` and writes it there. Returns +/// the path, or `None` when the dialog was dismissed. +#[tauri::command] +pub async fn save_text_file( + window: tauri::WebviewWindow, + suggested_name: String, + kind: SaveKind, + contents: String, +) -> HostResult> { + let (label, extensions) = kind.filter(); + let (sender, receiver) = tokio::sync::oneshot::channel(); + window + .dialog() + .file() + .set_parent(&window) + .set_file_name(file_name_only(&suggested_name)) + .add_filter(label, extensions) + .save_file(move |picked| { + let _ = sender.send(picked); + }); + let picked = receiver + .await + .map_err(|_| HostError::Internal("The save dialog closed unexpectedly.".into()))?; + let Some(picked) = picked else { + return Ok(None); + }; + let path = picked + .into_path() + .map_err(|err| HostError::Internal(format!("That location cannot be written to: {err}")))?; + let shown = path.display().to_string(); + tauri::async_runtime::spawn_blocking(move || write_text(&path, &contents)) + .await + .map_err(|err| HostError::Internal(format!("Could not save the file: {err}")))??; + Ok(Some(shown)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_suggested_name_never_carries_a_folder() { + assert_eq!(file_name_only("result.csv"), "result.csv"); + assert_eq!(file_name_only("../../etc/result.csv"), "result.csv"); + assert_eq!(file_name_only("/tmp/result.csv"), "result.csv"); + assert_eq!(file_name_only(""), "export"); + assert_eq!(file_name_only(".."), "export"); + #[cfg(windows)] + assert_eq!(file_name_only(r"C:\Windows\result.csv"), "result.csv"); + } + + #[test] + fn each_kind_offers_its_own_file_type() { + assert_eq!(SaveKind::Csv.filter().1, ["csv"]); + assert_eq!(SaveKind::Json.filter().1, ["json"]); + assert_eq!(SaveKind::Jsonl.filter().1, ["jsonl"]); + let kind: SaveKind = serde_json::from_str("\"jsonl\"").unwrap(); + assert_eq!(kind, SaveKind::Jsonl); + } + + #[test] + fn text_is_written_as_given_and_a_failure_names_the_file() { + let dir = std::env::temp_dir().join(format!("wb-save-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join("out.csv"); + write_text(&file, "a,b\r\n1,2\r\n").unwrap(); + assert_eq!(std::fs::read_to_string(&file).unwrap(), "a,b\r\n1,2\r\n"); + + let missing = dir.join("no-such-folder").join("out.csv"); + let err = write_text(&missing, "x").unwrap_err(); + assert!(err.to_string().contains("out.csv"), "{err}"); + let _ = std::fs::remove_dir_all(&dir); + } +} diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs new file mode 100644 index 0000000..93722af --- /dev/null +++ b/src-tauri/src/lib.rs @@ -0,0 +1,222 @@ +//! StackQL Workbench host. +//! +//! The host owns every process, connection and secret. The webview reaches it +//! only through the typed IPC commands and events defined in [`ipc`]. + +pub mod activity; +pub mod agent; +pub mod applog; +pub mod config; +pub mod connection; +pub mod engine; +pub mod error; +pub mod icons; +pub mod ipc; +pub mod library; +pub mod query; +pub mod secrets; +pub mod util; +pub mod webview_runtime; + +use std::sync::Arc; + +use tauri::{Emitter, Manager, RunEvent}; + +use crate::activity::History; +use crate::agent::runtime::AgentRuntime; +use crate::applog::AppLog; +use crate::config::SettingsStore; +use crate::connection::local::LocalConnection; +use crate::connection::{Connection, EngineState, EngineStatus}; +use crate::engine::approot::Defaults as ApprootDefaults; +use crate::icons::ProviderIcons; +use crate::ipc::AppState; +use crate::library::Library; +use crate::secrets::{KeychainStore, MemoryStore, SecretStore}; + +fn setup( + app: &tauri::App, + bundled_webview: Option<&std::path::Path>, +) -> Result<(), Box> { + let config_dir = app.path().app_config_dir()?; + let data_dir = app.path().app_data_dir()?; + let cache_dir = app.path().app_cache_dir()?; + + let settings = Arc::new(SettingsStore::load(config_dir.join("settings.json"))); + // The engine's provider cache goes in a folder beside this executable, + // or under the app data directory when that place cannot be written to. + // The operator can name another folder in settings. The engine's own + // default would be whatever directory the app was started from. + let approot_defaults = ApprootDefaults::for_executable( + std::env::current_exe().ok().as_deref(), + data_dir.join("engine"), + ); + let connection: Arc = Arc::new(LocalConnection::new( + approot_defaults, + data_dir.join("audit"), + settings.clone(), + )?); + + // The app's own log, one file for each run. It is apart from the + // engine's audit log, which the engine writes. + let log = Arc::new(AppLog::start(&data_dir.join("logs"))); + // On Windows the page renderer is either the one shipped beside the app + // or the system's. Which one is worth having on record. + if cfg!(windows) { + log.info( + "webview_runtime", + serde_json::json!({ + "source": if bundled_webview.is_some() { "beside the app" } else { "system" }, + "folder": bundled_webview.map(|folder| folder.display().to_string()), + }), + ); + } + + // Forward every status change to the webview, and note in the log when + // the engine comes up or fails to. + let handle = app.handle().clone(); + let mut status = connection.watch_status(); + let status_log = log.clone(); + tauri::async_runtime::spawn(async move { + let mut last_state = None; + loop { + let current = status.borrow_and_update().clone(); + if last_state != Some(current.state) { + last_state = Some(current.state); + log_engine_state(&status_log, ¤t); + } + let _ = handle.emit(ipc::ENGINE_STATUS_EVENT, current); + if status.changed().await.is_err() { + break; + } + } + }); + + // Bring the engine up without holding up the window. + let starting = connection.clone(); + tauri::async_runtime::spawn(async move { + starting.start().await; + }); + + // API keys live in the OS keychain. If it cannot be opened, keys are + // held in memory for this run and the settings pane says so. + let (secrets, keychain_available): (Arc, bool) = match KeychainStore::open() { + Ok(store) => (Arc::new(store), true), + Err(_) => (Arc::new(MemoryStore::default()), false), + }; + + app.manage(AppState { + agent: Arc::new( + AgentRuntime::new(connection.clone()) + .with_delegate_dir(data_dir.join("agents").join("copilot")), + ), + connection, + settings, + icons: Arc::new(ProviderIcons::new(cache_dir.join("provider-icons"))), + library: Arc::new(Library::new(cache_dir.join("query-library"))), + secrets, + keychain_available, + history: Arc::new(History::new(data_dir.join("history.jsonl"))), + log, + }); + Ok(()) +} + +/// Writes a change of the engine's state to the app's log. A failure goes +/// in with its reason and the engine's last lines, which the banner also +/// shows. The environment the engine was given is never part of a status. +fn log_engine_state(log: &AppLog, status: &EngineStatus) { + match status.state { + EngineState::Running => log.info( + "engine_running", + serde_json::json!({ + "location": status.location, + "foundVia": status.location_source, + "version": status.version, + "endpoint": status.endpoint, + "dataFolder": status.data_folder, + }), + ), + EngineState::Failed => log.error( + "engine_failed", + serde_json::json!({ + "location": status.location, + "error": status.error, + "logTail": status.log_tail, + }), + ), + EngineState::Stopped | EngineState::Starting => {} + } +} + +/// Starts the app. Does not return until the app exits. +pub fn run() { + // First, before anything can start a thread: use the page renderer that + // was shipped beside the app, when there is one. + let bundled_webview = webview_runtime::use_bundled(); + // Then, before anything is started: without a page renderer there is no + // window to say anything in, so say it in a dialog of the system's and + // stop. This returns at once where a renderer is found. + webview_runtime::require(); + + let built = tauri::Builder::default() + // The save dialog, used from the host only. The webview has no access to it. + .plugin(tauri_plugin_dialog::init()) + // Opens the Help menu's links in the browser, from the host only. + .plugin(tauri_plugin_opener::init()) + .setup(move |app| setup(app, bundled_webview.as_deref())) + .invoke_handler(tauri::generate_handler![ + ipc::engine_status, + ipc::engine_restart, + ipc::settings_get, + ipc::settings_save, + ipc::query_run, + ipc::query_abandon, + ipc::clipboard_write_text, + ipc::provider_icons, + ipc::explorer_providers, + ipc::explorer_registry, + ipc::explorer_services, + ipc::explorer_resources, + ipc::explorer_methods, + ipc::explorer_fields, + ipc::explorer_method_fields, + ipc::agent_config_get, + ipc::agent_config_save, + ipc::agent_config_clear, + ipc::agent_set_safety_mode, + ipc::agent_send, + ipc::agent_approve, + ipc::agent_stop, + ipc::agent_reset, + ipc::agent_delegate_info, + ipc::activity_list, + ipc::save::save_text_file, + ipc::links::open_link, + ipc::links::reveal_log, + ipc::library_index, + ipc::library_document, + ]) + .build(tauri::generate_context!()); + + let app = match built { + Ok(app) => app, + Err(err) => { + eprintln!("stackql-workbench failed to start: {err}"); + std::process::exit(1); + } + }; + + app.run(|handle, event| { + // A clean exit stops the engine here. A crash or a force quit is + // covered by the supervisor, which does not rely on this code running. + if let RunEvent::Exit = event + && let Some(state) = handle.try_state::() + { + let connection = state.connection.clone(); + tauri::async_runtime::block_on(async move { + connection.shutdown().await; + }); + } + }); +} diff --git a/src-tauri/src/library/mod.rs b/src-tauri/src/library/mod.rs new file mode 100644 index 0000000..3bb544d --- /dev/null +++ b/src-tauri/src/library/mod.rs @@ -0,0 +1,496 @@ +//! The query library, for the operator. +//! +//! The library is published in the `stackql/query-library.stackql.io` +//! repository: an index of its entries, and one markdown document for each +//! entry. The webview makes no network calls of its own, so the host fetches +//! both, keeps them in the app cache directory and hands the webview the +//! index and the text of a document. +//! +//! One host is contacted, and only under that repository's path. An entry +//! is named by its id, which is checked before it is put in an address. +//! +//! Nothing here runs a statement. An entry's statement is a template the +//! operator opens in the editor. + +use std::path::{Path, PathBuf}; +use std::time::{Duration, SystemTime}; + +use serde::{Deserialize, Serialize}; + +use crate::error::{HostError, HostResult}; + +const BASE: &str = "https://raw.githubusercontent.com/stackql/query-library.stackql.io/main"; +const INDEX_PATH: &str = "static/docs/query-library/index.json"; +const DOCUMENTS_PATH: &str = "query-library/queries"; + +/// How long a downloaded index is used before it is fetched again. +const INDEX_MAX_AGE: Duration = Duration::from_secs(6 * 60 * 60); +/// How long a downloaded document is used before it is fetched again. +const DOCUMENT_MAX_AGE: Duration = Duration::from_secs(24 * 60 * 60); +const MAX_INDEX_BYTES: usize = 4 * 1024 * 1024; +const MAX_DOCUMENT_BYTES: usize = 512 * 1024; +const REQUEST_TIMEOUT: Duration = Duration::from_secs(10); +const MAX_ID_CHARS: usize = 200; + +/// One entry of the library, as its index describes it. Fields the index +/// leaves out are empty. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all(serialize = "camelCase"))] +pub struct LibraryEntry { + /// For example `github/repos/org-repos-list`. Also the document's path. + pub id: String, + #[serde(default)] + pub title: String, + #[serde(default)] + pub description: String, + #[serde(default)] + pub providers: Vec, + #[serde(default)] + pub services: Vec, + #[serde(default)] + pub tags: Vec, + #[serde(default)] + pub keywords: Vec, + #[serde(default)] + pub intent_keywords: Vec, + /// The library's own word on whether the statement changes anything. + #[serde(default)] + pub mutation: bool, + #[serde(default)] + pub verb: String, + /// For example `stable` or `draft`. + #[serde(default)] + pub status: String, + #[serde(default)] + pub required_params: Vec, +} + +#[derive(Debug, Deserialize)] +struct RawIndex { + #[serde(default)] + build_id: String, + #[serde(default)] + entries: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct LibraryIndex { + pub entries: Vec, + /// The library build the index came from. + pub build_id: String, + /// The library could not be reached, and this is the copy kept from + /// an earlier time. + pub from_cache: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct LibraryDocument { + pub id: String, + /// The document without its front matter. + pub markdown: String, + /// The entry's statement: the first SQL block under its Query heading. + pub statement: Option, +} + +/// Whether an id is safe to put in an address and a file name: two to four +/// parts separated by slashes, each made of lower-case letters, digits, +/// underscores and hyphens. +pub fn valid_id(id: &str) -> bool { + if id.is_empty() || id.len() > MAX_ID_CHARS { + return false; + } + let parts: Vec<&str> = id.split('/').collect(); + (2..=4).contains(&parts.len()) + && parts.iter().all(|part| { + !part.is_empty() + && part + .chars() + .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '_' | '-')) + }) +} + +/// Reads the index. Entries whose id could not be fetched later are left out. +pub fn parse_index(text: &str) -> HostResult<(String, Vec)> { + let raw: RawIndex = serde_json::from_str(text).map_err(|err| { + HostError::Internal(format!("The query library index could not be read: {err}")) + })?; + let entries = raw + .entries + .into_iter() + .filter(|entry| valid_id(&entry.id)) + .collect(); + Ok((raw.build_id, entries)) +} + +/// The document without the front matter between its opening `---` lines. +pub fn strip_front_matter(text: &str) -> &str { + let Some(rest) = text + .strip_prefix("---\n") + .or_else(|| text.strip_prefix("---\r\n")) + else { + return text; + }; + let mut offset = 0; + for line in rest.split_inclusive('\n') { + if line.trim_end() == "---" { + return rest[offset + line.len()..].trim_start_matches(['\r', '\n']); + } + offset += line.len(); + } + // An opening line with no closing one. Leave the text as it is. + text +} + +/// The first SQL block under the `## Query` heading, or failing that the +/// first SQL block in the document. +pub fn first_statement(markdown: &str) -> Option { + let lines: Vec<&str> = markdown.lines().collect(); + let heading = lines + .iter() + .position(|line| line.trim().eq_ignore_ascii_case("## query")); + sql_block(&lines[heading.unwrap_or(0)..]).or_else(|| sql_block(&lines)) +} + +fn sql_block(lines: &[&str]) -> Option { + let start = lines.iter().position(|line| { + let fence = line.trim(); + fence.eq_ignore_ascii_case("```sql") + })?; + let body: Vec<&str> = lines[start + 1..] + .iter() + .take_while(|line| line.trim() != "```") + .copied() + .collect(); + let text = body.join("\n").trim().to_string(); + (!text.is_empty()).then_some(text) +} + +/// Fetches and caches the library. +pub struct Library { + http: Option, + cache_dir: PathBuf, +} + +impl Library { + pub fn new(cache_dir: PathBuf) -> Self { + let http = reqwest::Client::builder() + .timeout(REQUEST_TIMEOUT) + .connect_timeout(Duration::from_secs(5)) + .https_only(true) + .redirect(reqwest::redirect::Policy::none()) + .user_agent(concat!("stackql-workbench/", env!("CARGO_PKG_VERSION"))) + .build() + .ok(); + Self { http, cache_dir } + } + + /// A library that never touches the network. It answers from the cache + /// directory only. + pub fn offline(cache_dir: PathBuf) -> Self { + Self { + http: None, + cache_dir, + } + } + + /// The index. A copy fetched recently is used as it is, unless `refresh` + /// asks for a new one. When the library cannot be reached an older copy + /// is returned and marked as such. + pub async fn index(&self, refresh: bool) -> HostResult { + let path = self.cache_dir.join("index.json"); + let cached = read_cached(&path).and_then(|(text, age)| { + parse_index(&text) + .ok() + .map(|(build_id, entries)| (build_id, entries, age)) + }); + + if !refresh + && let Some((build_id, entries, age)) = &cached + && *age < INDEX_MAX_AGE + { + return Ok(LibraryIndex { + entries: entries.clone(), + build_id: build_id.clone(), + from_cache: false, + }); + } + + let url = format!("{BASE}/{INDEX_PATH}"); + if let Some(text) = self.fetch(&url, MAX_INDEX_BYTES).await + && let Ok((build_id, entries)) = parse_index(&text) + { + write_cache(&path, text.as_bytes()); + return Ok(LibraryIndex { + entries, + build_id, + from_cache: false, + }); + } + + match cached { + Some((build_id, entries, _)) => Ok(LibraryIndex { + entries, + build_id, + from_cache: true, + }), + None => Err(HostError::Internal( + "The query library could not be reached, and there is no earlier copy to show." + .into(), + )), + } + } + + /// The document of one entry. + pub async fn document(&self, id: &str) -> HostResult { + if !valid_id(id) { + return Err(HostError::Internal(format!( + "'{}' is not a query library entry.", + id.escape_default() + ))); + } + let path = self + .cache_dir + .join("documents") + .join(format!("{}.md", id.replace('/', "__"))); + let cached = read_cached(&path); + + let text = match &cached { + Some((text, age)) if *age < DOCUMENT_MAX_AGE => Some(text.clone()), + _ => { + let url = format!("{BASE}/{DOCUMENTS_PATH}/{id}.md"); + match self.fetch(&url, MAX_DOCUMENT_BYTES).await { + Some(text) => { + write_cache(&path, text.as_bytes()); + Some(text) + } + // An old copy is better than none. + None => cached.map(|(text, _)| text), + } + } + }; + let Some(text) = text else { + return Err(HostError::Internal(format!( + "The query library entry {id} could not be fetched." + ))); + }; + + let markdown = strip_front_matter(&text).to_string(); + let statement = first_statement(&markdown); + Ok(LibraryDocument { + id: id.to_string(), + markdown, + statement, + }) + } + + /// Fetches text, giving up on anything that is not a success, is larger + /// than `limit` or is not UTF-8. + async fn fetch(&self, url: &str, limit: usize) -> Option { + let http = self.http.as_ref()?; + let response = http.get(url).send().await.ok()?; + if !response.status().is_success() { + return None; + } + if response + .content_length() + .is_some_and(|length| length > limit as u64) + { + return None; + } + let bytes = response.bytes().await.ok()?; + if bytes.len() > limit { + return None; + } + String::from_utf8(bytes.to_vec()).ok() + } +} + +fn read_cached(path: &Path) -> Option<(String, Duration)> { + let text = std::fs::read_to_string(path).ok()?; + let modified = std::fs::metadata(path).ok()?.modified().ok()?; + let age = SystemTime::now().duration_since(modified).ok()?; + Some((text, age)) +} + +/// The cache is a convenience. A failed write is not worth reporting. +fn write_cache(path: &Path, bytes: &[u8]) { + if let Some(dir) = path.parent() { + let _ = std::fs::create_dir_all(dir); + } + let _ = std::fs::write(path, bytes); +} + +#[cfg(test)] +mod tests { + use super::*; + + const INDEX: &str = r#"{ + "build_id": "ql-1", + "entries": [ + { + "id": "github/repos/org-repos-list", + "title": "GitHub repositories in an organization", + "description": "Lists all repositories.", + "providers": ["github"], + "services": ["repos"], + "tags": ["github", "repos", "inventory"], + "keywords": ["repo list"], + "intent_keywords": ["list repos in my github org"], + "mutation": false, + "verb": "select", + "status": "stable", + "required_params": ["org"] + }, + { "id": "aws/s3/buckets-list" }, + { "id": "../../etc/passwd", "title": "not an entry" }, + { "id": "Upper/Case/x" } + ] + }"#; + + const DOCUMENT: &str = "---\ntitle: GitHub repositories\nparams:\n - name: org\n---\n\nLists every repository.\n\n## Query\n\n```sql\nSELECT name\nFROM github.repos.repos\nWHERE org = '{{org}}';\n```\n\n## Variation: sorted\n\n```sql\nSELECT name FROM github.repos.repos WHERE org = '{{org}}' AND sort = 'pushed';\n```\n"; + + fn cache(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("wb-library-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir + } + + #[test] + fn an_id_is_checked_before_it_is_used() { + assert!(valid_id("github/repos/org-repos-list")); + assert!(valid_id("aws/cloud_control/resource-request-by-token")); + assert!(valid_id("a/b")); + for bad in [ + "", + "single", + "a/b/c/d/e", + "../x", + "a//b", + "a/b/", + "/a/b", + "A/b", + "a/b.md", + "a/b c", + "a\\b", + "https://example.com/x", + ] { + assert!(!valid_id(bad), "{bad}"); + } + assert!(!valid_id(&format!("a/{}", "b".repeat(300)))); + } + + #[test] + fn the_index_is_read_and_unusable_ids_are_left_out() { + let (build, entries) = parse_index(INDEX).unwrap(); + assert_eq!(build, "ql-1"); + let ids: Vec<&str> = entries.iter().map(|e| e.id.as_str()).collect(); + assert_eq!(ids, ["github/repos/org-repos-list", "aws/s3/buckets-list"]); + assert_eq!(entries[0].required_params, ["org"]); + assert_eq!(entries[0].intent_keywords, ["list repos in my github org"]); + // An entry with only an id still reads, with everything else empty. + assert_eq!(entries[1].title, ""); + assert!(!entries[1].mutation); + assert!(parse_index("not json").is_err()); + } + + #[test] + fn an_entry_goes_to_the_webview_in_camel_case() { + let (_, entries) = parse_index(INDEX).unwrap(); + let json = serde_json::to_value(&entries[0]).unwrap(); + assert_eq!(json["requiredParams"], serde_json::json!(["org"])); + assert_eq!( + json["intentKeywords"], + serde_json::json!(["list repos in my github org"]) + ); + } + + #[test] + fn front_matter_is_taken_off() { + let body = strip_front_matter(DOCUMENT); + assert!(body.starts_with("Lists every repository."), "{body}"); + assert!(!body.contains("params:")); + // No front matter, or one that never closes, leaves the text alone. + assert_eq!(strip_front_matter("# Title\n\ntext"), "# Title\n\ntext"); + assert_eq!( + strip_front_matter("---\ntitle: x\nno end"), + "---\ntitle: x\nno end" + ); + assert!(strip_front_matter("---\r\ntitle: x\r\n---\r\n\r\nBody").starts_with("Body")); + } + + #[test] + fn the_statement_is_the_first_sql_block_under_the_query_heading() { + let statement = first_statement(strip_front_matter(DOCUMENT)).unwrap(); + assert_eq!( + statement, + "SELECT name\nFROM github.repos.repos\nWHERE org = '{{org}}';" + ); + // A block before the heading is not the entry's statement. + let early = "```sql\nSELECT 1;\n```\n\n## Query\n\n```sql\nSELECT 2;\n```\n"; + assert_eq!(first_statement(early).unwrap(), "SELECT 2;"); + // With no Query heading the first block is used. + assert_eq!( + first_statement("text\n\n```sql\nSELECT 3;\n```\n").unwrap(), + "SELECT 3;" + ); + assert_eq!(first_statement("no code here"), None); + assert_eq!(first_statement("```python\nprint(1)\n```"), None); + } + + #[tokio::test] + async fn a_cached_index_is_served_without_the_network() { + let dir = cache("index"); + std::fs::write(dir.join("index.json"), INDEX).unwrap(); + let index = Library::offline(dir.clone()).index(false).await.unwrap(); + assert_eq!(index.entries.len(), 2); + assert_eq!(index.build_id, "ql-1"); + assert!(!index.from_cache); + // Asked for a new copy with no network, the old one is marked as old. + let again = Library::offline(dir.clone()).index(true).await.unwrap(); + assert!(again.from_cache); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn with_no_network_and_no_copy_the_index_is_an_error() { + let dir = cache("empty"); + let err = Library::offline(dir.clone()) + .index(false) + .await + .unwrap_err(); + assert!(err.to_string().contains("could not be reached"), "{err}"); + let _ = std::fs::remove_dir_all(dir); + } + + #[tokio::test] + async fn a_cached_document_is_read_into_its_body_and_statement() { + let dir = cache("document"); + std::fs::create_dir_all(dir.join("documents")).unwrap(); + std::fs::write( + dir.join("documents") + .join("github__repos__org-repos-list.md"), + DOCUMENT, + ) + .unwrap(); + let library = Library::offline(dir.clone()); + let document = library + .document("github/repos/org-repos-list") + .await + .unwrap(); + assert!(document.markdown.starts_with("Lists every repository.")); + assert!( + document + .statement + .as_deref() + .is_some_and(|sql| sql.starts_with("SELECT name")) + ); + + assert!(library.document("github/repos/missing").await.is_err()); + let refused = library.document("../secrets").await.unwrap_err(); + assert!(refused.to_string().contains("not a query library entry")); + let _ = std::fs::remove_dir_all(dir); + } +} diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rs new file mode 100644 index 0000000..fac59b5 --- /dev/null +++ b/src-tauri/src/main.rs @@ -0,0 +1,6 @@ +// Prevents an extra console window on Windows in release builds. +#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] + +fn main() { + stackql_workbench_lib::run(); +} diff --git a/src-tauri/src/query/explorer.rs b/src-tauri/src/query/explorer.rs new file mode 100644 index 0000000..edae6c9 --- /dev/null +++ b/src-tauri/src/query/explorer.rs @@ -0,0 +1,586 @@ +//! The metadata statements behind the explorer tree, and the mapping from +//! their results to typed items. +//! +//! Statements are built here from validated, quoted identifiers. Names that +//! arrive from the webview are never interpolated as they are. +//! +//! Column names and shapes were read from the real engine and are recorded +//! in `docs/spike-pgwire.md`. + +use serde::Serialize; + +use super::result::{ResultSet, Row}; +use crate::error::{HostError, HostResult}; + +const MAX_IDENTIFIER_CHARS: usize = 256; + +/// Validates a provider, service, resource or method name and returns it in +/// double quotes. +/// +/// The engine accepts double-quoted identifiers in every statement used +/// here. Quoting always, instead of only when needed, means a name can never +/// be read as a keyword. Names from the engine are made of letters, digits, +/// underscores, hyphens and dots. Anything else is refused, which rules out +/// quotes, semicolons, whitespace and control characters. +pub fn quote_identifier(name: &str) -> HostResult { + if name.is_empty() { + return Err(HostError::InvalidIdentifier("The name is empty.".into())); + } + if name.chars().count() > MAX_IDENTIFIER_CHARS { + return Err(HostError::InvalidIdentifier("The name is too long.".into())); + } + let valid = name + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.')); + if !valid { + return Err(HostError::InvalidIdentifier(format!( + "'{}' is not a valid name. Names may contain letters, digits, underscores, hyphens and dots.", + name.escape_default() + ))); + } + Ok(format!("\"{name}\"")) +} + +fn qualified(parts: &[&str]) -> HostResult { + let quoted: HostResult> = parts.iter().map(|p| quote_identifier(p)).collect(); + Ok(quoted?.join(".")) +} + +pub const PROVIDERS_SQL: &str = "SHOW PROVIDERS"; +/// What the registry offers: one row for each provider, with its version. +pub const REGISTRY_LIST_SQL: &str = "REGISTRY LIST"; + +pub fn services_sql(provider: &str) -> HostResult { + Ok(format!( + "SHOW EXTENDED SERVICES IN {}", + qualified(&[provider])? + )) +} + +pub fn resources_sql(provider: &str, service: &str) -> HostResult { + Ok(format!( + "SHOW EXTENDED RESOURCES IN {}", + qualified(&[provider, service])? + )) +} + +pub fn methods_sql(provider: &str, service: &str, resource: &str) -> HostResult { + Ok(format!( + "SHOW EXTENDED METHODS IN {}", + qualified(&[provider, service, resource])? + )) +} + +pub fn fields_sql(provider: &str, service: &str, resource: &str) -> HostResult { + Ok(format!( + "DESCRIBE EXTENDED {}", + qualified(&[provider, service, resource])? + )) +} + +pub fn method_fields_sql( + provider: &str, + service: &str, + resource: &str, + method: &str, +) -> HostResult { + // The keyword order matters: DESCRIBE EXTENDED METHOD is a syntax error. + Ok(format!( + "DESCRIBE METHOD EXTENDED {}", + qualified(&[provider, service, resource, method])? + )) +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Provider { + pub name: String, + pub version: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Service { + /// The name to use in statements. + pub name: String, + /// `:`. Not a path. + pub id: String, + pub title: String, + pub description: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Resource { + pub name: String, + /// The fully qualified name, `..`. + pub id: String, + pub description: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Method { + pub name: String, + /// `SELECT`, `INSERT`, `UPDATE`, `REPLACE`, `DELETE` or `EXEC`. + pub sql_verb: String, + pub required_params: Vec, + pub description: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Field { + pub name: String, + /// May be empty, for example for some view columns. + #[serde(rename = "type")] + pub type_name: String, + pub description: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct MethodField { + pub name: String, + #[serde(rename = "type")] + pub type_name: String, + /// `input_required`, `input_optional` or `output`. + pub param_type: String, + pub shape: String, + pub description: String, +} + +/// Reads columns by name, so a change in column order does not break the +/// explorer. A missing required column is an error. A missing optional +/// column reads as empty. +struct Reader<'a> { + result: &'a ResultSet, + statement: &'static str, +} + +impl<'a> Reader<'a> { + fn new(result: &'a ResultSet, statement: &'static str) -> Self { + Self { result, statement } + } + + fn required(&self, name: &str) -> HostResult { + self.result.column(name).ok_or_else(|| { + HostError::Query(format!( + "{} returned an unexpected shape: no '{name}' column. Columns were: {}.", + self.statement, + self.result.columns.join(", ") + )) + }) + } + + fn optional(&self, name: &str) -> Option { + self.result.column(name) + } +} + +fn cell(row: &Row, index: usize) -> String { + row.get(index).cloned().flatten().unwrap_or_default() +} + +fn opt_cell(row: &Row, index: Option) -> String { + index.map(|i| cell(row, i)).unwrap_or_default() +} + +pub fn map_providers(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "SHOW PROVIDERS"); + let name = reader.required("name")?; + let version = reader.optional("version"); + Ok(result + .rows + .iter() + .map(|row| Provider { + name: cell(row, name), + version: opt_cell(row, version), + }) + .collect()) +} + +/// Maps `REGISTRY LIST`. The provider's name is in the `provider` column. +pub fn map_registry(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "REGISTRY LIST"); + let name = reader.required("provider")?; + let version = reader.optional("version"); + Ok(result + .rows + .iter() + .map(|row| Provider { + name: cell(row, name), + version: opt_cell(row, version), + }) + .collect()) +} + +/// Providers the explorer leaves out. The engine has one provider built +/// in, `stackql_preview`, which is not shown for now. It is named here and +/// nowhere else, so taking the name out brings it back. +/// +/// Only the tree leaves it out. A statement the operator runs, such as +/// `SHOW PROVIDERS`, still shows what the engine says, and so does what the +/// engine tells a model. +pub const HIDDEN_PROVIDERS: &[&str] = &["stackql_preview"]; + +/// The providers the explorer lists. +pub fn visible_providers(providers: Vec) -> Vec { + providers + .into_iter() + .filter(|provider| !HIDDEN_PROVIDERS.contains(&provider.name.as_str())) + .collect() +} + +pub fn map_services(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "SHOW SERVICES"); + let name = reader.required("name")?; + let id = reader.optional("id"); + let title = reader.optional("title"); + let description = reader.optional("description"); + Ok(result + .rows + .iter() + .map(|row| Service { + name: cell(row, name), + id: opt_cell(row, id), + title: opt_cell(row, title), + description: opt_cell(row, description), + }) + .collect()) +} + +pub fn map_resources(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "SHOW RESOURCES"); + let name = reader.required("name")?; + let id = reader.optional("id"); + let description = reader.optional("description"); + Ok(result + .rows + .iter() + .map(|row| Resource { + name: cell(row, name), + id: opt_cell(row, id), + description: opt_cell(row, description), + }) + .collect()) +} + +pub fn map_methods(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "SHOW METHODS"); + let name = reader.required("MethodName")?; + let verb = reader.optional("SQLVerb"); + let params = reader.optional("RequiredParams"); + let description = reader.optional("description"); + Ok(result + .rows + .iter() + .map(|row| Method { + name: cell(row, name), + sql_verb: opt_cell(row, verb), + required_params: opt_cell(row, params) + .split(',') + .map(str::trim) + .filter(|p| !p.is_empty()) + .map(str::to_string) + .collect(), + description: opt_cell(row, description), + }) + .collect()) +} + +pub fn map_fields(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "DESCRIBE"); + let name = reader.required("name")?; + let type_name = reader.optional("type"); + let description = reader.optional("description"); + Ok(result + .rows + .iter() + .map(|row| Field { + name: cell(row, name), + type_name: opt_cell(row, type_name), + description: opt_cell(row, description), + }) + .collect()) +} + +pub fn map_method_fields(result: &ResultSet) -> HostResult> { + let reader = Reader::new(result, "DESCRIBE METHOD"); + let name = reader.required("name")?; + let param_type = reader.required("param_type")?; + let type_name = reader.optional("type"); + let shape = reader.optional("shape"); + let description = reader.optional("description"); + Ok(result + .rows + .iter() + .map(|row| MethodField { + name: cell(row, name), + type_name: opt_cell(row, type_name), + param_type: cell(row, param_type), + shape: opt_cell(row, shape), + description: opt_cell(row, description), + }) + .collect()) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn result(columns: &[&str], rows: &[&[&str]]) -> ResultSet { + ResultSet { + columns: columns.iter().map(|c| (*c).to_string()).collect(), + rows: rows + .iter() + .map(|r| r.iter().map(|v| Some((*v).to_string())).collect()) + .collect(), + notices: Vec::new(), + } + } + + #[test] + fn the_built_in_provider_is_left_out_of_the_tree_and_nothing_else_is() { + let provider = |name: &str| Provider { + name: name.into(), + version: "v1".into(), + }; + let shown = visible_providers(vec![ + provider("github"), + provider("stackql_preview"), + provider("aws"), + // A name that only starts the same way is some other provider. + provider("stackql_preview_extras"), + ]); + let names: Vec<&str> = shown.iter().map(|p| p.name.as_str()).collect(); + assert_eq!(names, ["github", "aws", "stackql_preview_extras"]); + assert!(visible_providers(vec![provider("stackql_preview")]).is_empty()); + } + + #[test] + fn the_registry_listing_is_read_by_its_own_column_names() { + let listed = map_registry(&result( + &["provider", "version"], + &[&["aws", "v26.11.00490"], &["github", "v26.08.00448"]], + )) + .unwrap(); + assert_eq!(listed.len(), 2); + assert_eq!(listed[1].name, "github"); + assert_eq!(listed[1].version, "v26.08.00448"); + // SHOW PROVIDERS names the column differently, so it is not a listing. + assert!(map_registry(&result(&["name", "version"], &[&["aws", "v1"]])).is_err()); + } + + #[test] + fn plain_names_are_quoted() { + assert_eq!(quote_identifier("github").unwrap(), "\"github\""); + assert_eq!(quote_identifier("vw_info").unwrap(), "\"vw_info\""); + assert_eq!(quote_identifier("openssl-3.1").unwrap(), "\"openssl-3.1\""); + } + + #[test] + fn names_that_could_break_out_of_a_statement_are_refused() { + for bad in [ + "", + "a b", + "a;b", + "a\"b", + "a'b", + "a`b", + "a\nb", + "a--b; DROP", + "a/*b*/", + "a\\b", + "naïve", + ] { + assert!( + matches!(quote_identifier(bad), Err(HostError::InvalidIdentifier(_))), + "{bad:?} should be refused" + ); + } + assert!(quote_identifier(&"x".repeat(MAX_IDENTIFIER_CHARS + 1)).is_err()); + } + + #[test] + fn statements_use_quoted_qualified_names() { + assert_eq!( + services_sql("github").unwrap(), + "SHOW EXTENDED SERVICES IN \"github\"" + ); + assert_eq!( + resources_sql("github", "repos").unwrap(), + "SHOW EXTENDED RESOURCES IN \"github\".\"repos\"" + ); + assert_eq!( + methods_sql("github", "repos", "repos").unwrap(), + "SHOW EXTENDED METHODS IN \"github\".\"repos\".\"repos\"" + ); + assert_eq!( + fields_sql("homebrew", "formula", "vw_info").unwrap(), + "DESCRIBE EXTENDED \"homebrew\".\"formula\".\"vw_info\"" + ); + assert_eq!( + method_fields_sql("homebrew", "formula", "formula", "get_formula").unwrap(), + "DESCRIBE METHOD EXTENDED \"homebrew\".\"formula\".\"formula\".\"get_formula\"" + ); + } + + #[test] + fn a_bad_part_fails_the_whole_statement() { + assert!(resources_sql("github", "repos; SELECT 1").is_err()); + assert!(method_fields_sql("a", "b", "c", "").is_err()); + } + + #[test] + fn providers_are_mapped() { + let rs = result( + &["name", "version"], + &[ + &["github", "v26.08.00448"], + &["stackql_preview", "internal"], + ], + ); + assert_eq!( + map_providers(&rs).unwrap(), + vec![ + Provider { + name: "github".into(), + version: "v26.08.00448".into() + }, + Provider { + name: "stackql_preview".into(), + version: "internal".into() + }, + ] + ); + } + + #[test] + fn services_are_mapped_by_column_name_not_position() { + // The engine's order is id, name, title, description, version, preferred. + let rs = result( + &["id", "name", "title", "description", "version", "preferred"], + &[&[ + "formula:v25.01.00292", + "formula", + "Homebrew Formulae API", + "API For Accessing Homebrew Formulae Information.", + "v25.01.00292", + "true", + ]], + ); + let services = map_services(&rs).unwrap(); + assert_eq!(services[0].name, "formula"); + assert_eq!(services[0].id, "formula:v25.01.00292"); + assert_eq!(services[0].title, "Homebrew Formulae API"); + + // A different order gives the same result. + let reordered = result(&["title", "name", "id"], &[&["T", "formula", "formula:v1"]]); + let services = map_services(&reordered).unwrap(); + assert_eq!(services[0].name, "formula"); + assert_eq!(services[0].title, "T"); + assert_eq!(services[0].description, ""); + } + + #[test] + fn resources_are_mapped() { + let rs = result( + &["name", "id", "description"], + &[&["formula", "homebrew.formula.formula", ""]], + ); + assert_eq!( + map_resources(&rs).unwrap(), + vec![Resource { + name: "formula".into(), + id: "homebrew.formula.formula".into(), + description: String::new(), + }] + ); + } + + #[test] + fn methods_split_required_params() { + let rs = result( + &["MethodName", "RequiredParams", "SQLVerb", "description"], + &[ + &["list_for_org", "org", "SELECT", "repos/list-for-org"], + &["list_public", "", "SELECT", "repos/list-public"], + &["create_fork", "owner, repo", "INSERT", "repos/create-fork"], + ], + ); + let methods = map_methods(&rs).unwrap(); + assert_eq!(methods[0].required_params, vec!["org"]); + assert_eq!(methods[1].required_params, Vec::::new()); + assert_eq!(methods[2].required_params, vec!["owner", "repo"]); + assert_eq!(methods[2].sql_verb, "INSERT"); + } + + #[test] + fn fields_are_mapped_and_serialise_type_as_type() { + let rs = result( + &["name", "type", "description"], + &[&["name", "string", ""], &["formula_name", "", ""]], + ); + let fields = map_fields(&rs).unwrap(); + assert_eq!(fields[0].type_name, "string"); + assert_eq!(fields[1].type_name, ""); + assert_eq!( + serde_json::to_value(&fields[0]).unwrap(), + serde_json::json!({ "name": "name", "type": "string", "description": "" }) + ); + } + + #[test] + fn method_fields_are_mapped() { + let rs = result( + &["name", "type", "param_type", "shape", "description"], + &[ + &["formula_name", "string", "input_required", "string", ""], + &["aliases", "array", "output", "array", ""], + ], + ); + let fields = map_method_fields(&rs).unwrap(); + assert_eq!(fields[0].param_type, "input_required"); + assert_eq!(fields[1].param_type, "output"); + assert_eq!( + serde_json::to_value(&fields[0]).unwrap(), + serde_json::json!({ + "name": "formula_name", + "type": "string", + "paramType": "input_required", + "shape": "string", + "description": "" + }) + ); + } + + #[test] + fn a_missing_required_column_is_reported_with_what_was_there() { + let rs = result(&["title"], &[&["x"]]); + let err = map_services(&rs).unwrap_err(); + let HostError::Query(message) = err else { + panic!("expected a query error"); + }; + assert!(message.contains("'name'")); + assert!(message.contains("title")); + } + + #[test] + fn nulls_and_short_rows_read_as_empty() { + let rs = ResultSet { + columns: vec!["name".into(), "version".into()], + rows: vec![vec![Some("only-name".into())], vec![Some("x".into()), None]], + notices: Vec::new(), + }; + let providers = map_providers(&rs).unwrap(); + assert_eq!(providers[0].version, ""); + assert_eq!(providers[1].version, ""); + } + + #[test] + fn an_empty_result_maps_to_an_empty_list() { + let rs = result(&["name", "version"], &[]); + assert_eq!(map_providers(&rs).unwrap(), Vec::new()); + } +} diff --git a/src-tauri/src/query/mod.rs b/src-tauri/src/query/mod.rs new file mode 100644 index 0000000..313ecc5 --- /dev/null +++ b/src-tauri/src/query/mod.rs @@ -0,0 +1,7 @@ +//! The query service: pg wire client, statement splitting, result shaping +//! and the explorer's metadata statements. + +pub mod explorer; +pub mod result; +pub mod session; +pub mod split; diff --git a/src-tauri/src/query/result.rs b/src-tauri/src/query/result.rs new file mode 100644 index 0000000..33f60f9 --- /dev/null +++ b/src-tauri/src/query/result.rs @@ -0,0 +1,407 @@ +//! Result types that cross IPC, and the pure logic that shapes them. +//! +//! What the engine sends is described in `docs/spike-pgwire.md`. In short: +//! every value is text, the command tag carries no row count, and notices +//! pile up on a connection. + +use serde::Serialize; + +/// One row. Values are text, or `None` for a protocol NULL. +pub type Row = Vec>; + +/// A pg notice. For this engine the useful text is in `detail`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Notice { + pub severity: String, + pub code: String, + pub message: String, + pub detail: Option, +} + +/// Why a statement failed. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct QueryError { + /// Severity from the server's error response, when there was one. + pub severity: Option, + /// SQLSTATE from the server. This engine sends `XXUUU` for everything. + pub code: Option, + pub message: String, + /// True when the connection is no longer usable. + pub connection_lost: bool, +} + +impl QueryError { + /// An error reported by the engine in an error response. + pub fn from_server(severity: &str, code: &str, message: &str) -> Self { + Self { + severity: Some(severity.to_string()), + code: Some(code.to_string()), + message: message.to_string(), + connection_lost: false, + } + } + + /// An error raised on the client side: connect failure, broken socket, + /// protocol violation. + pub fn from_client(message: impl Into, connection_lost: bool) -> Self { + Self { + severity: None, + code: None, + message: message.into(), + connection_lost, + } + } +} + +impl std::fmt::Display for QueryError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.message) + } +} + +/// Events streamed to the webview while a run is in progress. A run is one +/// or more statements, executed in order. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde( + rename_all = "camelCase", + rename_all_fields = "camelCase", + tag = "event", + content = "data" +)] +pub enum QueryEvent { + StatementStarted { + index: usize, + total: usize, + sql: String, + }, + /// Column names. Sent even when the statement returns no rows. + Columns { + index: usize, + columns: Vec, + }, + /// A batch of rows. Batches arrive in order. + Rows { + index: usize, + rows: Vec, + }, + Notice { + index: usize, + notice: Notice, + }, + /// Lines the engine wrote to stderr while the statement ran. + EngineLog { + index: usize, + lines: Vec, + }, + StatementFinished { + index: usize, + row_count: u64, + elapsed_ms: u64, + }, + StatementFailed { + index: usize, + error: QueryError, + elapsed_ms: u64, + }, +} + +/// The outcome of a whole run. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct RunSummary { + /// Statements found in the text. + pub statements: usize, + /// Statements that ran to completion. + pub completed: usize, + /// True when a statement failed. Later statements were not run. + pub failed: bool, + /// True when the operator stopped waiting. The engine has no cancel, so + /// the statement that was running may still complete there. + pub abandoned: bool, + pub elapsed_ms: u64, +} + +/// A complete result held in memory. Used for metadata statements, which are +/// small. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct ResultSet { + pub columns: Vec, + pub rows: Vec, + pub notices: Vec, +} + +impl ResultSet { + /// Index of a column by name. Column order is not relied on. + pub fn column(&self, name: &str) -> Option { + self.columns.iter().position(|c| c == name) + } +} + +/// Groups rows into batches so a large result crosses IPC in pieces. The +/// engine sends all rows at the end of a statement, so this does not make +/// rows appear sooner. It keeps any one IPC message small. +#[derive(Debug)] +pub struct Batcher { + rows: Vec, + bytes: usize, + max_rows: usize, + max_bytes: usize, + total: u64, +} + +impl Batcher { + pub const DEFAULT_MAX_ROWS: usize = 500; + pub const DEFAULT_MAX_BYTES: usize = 512 * 1024; + + pub fn new(max_rows: usize, max_bytes: usize) -> Self { + Self { + rows: Vec::new(), + bytes: 0, + max_rows: max_rows.max(1), + max_bytes: max_bytes.max(1), + total: 0, + } + } + + /// Adds a row. Returns a batch when one is full. + pub fn push(&mut self, row: Row) -> Option> { + self.bytes += row.iter().flatten().map(String::len).sum::(); + self.rows.push(row); + self.total += 1; + if self.rows.len() >= self.max_rows || self.bytes >= self.max_bytes { + self.take() + } else { + None + } + } + + /// Returns whatever is left. + pub fn finish(&mut self) -> Option> { + self.take() + } + + /// Rows seen so far. This is the row count, since the engine's command + /// tag does not carry one. + pub fn total(&self) -> u64 { + self.total + } + + fn take(&mut self) -> Option> { + if self.rows.is_empty() { + return None; + } + self.bytes = 0; + Some(std::mem::take(&mut self.rows)) + } +} + +impl Default for Batcher { + fn default() -> Self { + Self::new(Self::DEFAULT_MAX_ROWS, Self::DEFAULT_MAX_BYTES) + } +} + +/// Works out which part of a notice is new on a long-lived connection. +/// +/// The engine keeps one notice buffer per connection and never clears it. +/// After the first notice, every later statement on that connection gets the +/// whole accumulated text again, including statements that succeed. This +/// tracker remembers the text already reported and passes on only what was +/// appended. +#[derive(Debug, Default)] +pub struct NoticeTracker { + seen_detail: String, +} + +impl NoticeTracker { + /// Returns the notice with only its new text, or `None` when it carries + /// nothing that has not been reported already. + pub fn fresh(&mut self, notice: Notice) -> Option { + let Some(detail) = notice.detail.as_deref() else { + // Nothing to compare. Pass it through. + return Some(notice); + }; + if detail == self.seen_detail { + return None; + } + let new_part = if !self.seen_detail.is_empty() && detail.starts_with(&self.seen_detail) { + detail[self.seen_detail.len()..].trim_start() + } else { + detail + } + .to_string(); + self.seen_detail = detail.to_string(); + if new_part.is_empty() { + return None; + } + Some(Notice { + detail: Some(new_part), + ..notice + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn row(values: &[&str]) -> Row { + values.iter().map(|v| Some((*v).to_string())).collect() + } + + fn notice(detail: Option<&str>) -> Notice { + Notice { + severity: "NOTICE".into(), + code: "01000".into(), + message: "a notice level event has occurred".into(), + detail: detail.map(str::to_string), + } + } + + #[test] + fn batcher_flushes_on_row_count() { + let mut b = Batcher::new(2, usize::MAX); + assert_eq!(b.push(row(&["a"])), None); + assert_eq!(b.push(row(&["b"])), Some(vec![row(&["a"]), row(&["b"])])); + assert_eq!(b.push(row(&["c"])), None); + assert_eq!(b.finish(), Some(vec![row(&["c"])])); + assert_eq!(b.finish(), None); + assert_eq!(b.total(), 3); + } + + #[test] + fn batcher_flushes_on_size() { + let mut b = Batcher::new(usize::MAX, 10); + assert_eq!(b.push(row(&["12345"])), None); + // 5 + 6 bytes crosses the limit. + assert!(b.push(row(&["123456"])).is_some()); + // The byte counter starts again after a flush. + assert_eq!(b.push(row(&["1"])), None); + } + + #[test] + fn batcher_counts_nulls_as_empty() { + let mut b = Batcher::new(usize::MAX, 4); + assert_eq!(b.push(vec![None, None, None]), None); + assert_eq!(b.total(), 1); + } + + #[test] + fn batcher_with_no_rows_yields_nothing() { + let mut b = Batcher::default(); + assert_eq!(b.finish(), None); + assert_eq!(b.total(), 0); + } + + #[test] + fn first_notice_is_reported_whole() { + let mut t = NoticeTracker::default(); + let got = t + .fresh(notice(Some("http response status code: 404"))) + .unwrap(); + assert_eq!( + got.detail.as_deref(), + Some("http response status code: 404") + ); + } + + #[test] + fn a_repeat_of_the_same_text_is_old_news() { + // What the engine does for a successful statement after a failed one. + let mut t = NoticeTracker::default(); + t.fresh(notice(Some("first failure"))); + assert_eq!(t.fresh(notice(Some("first failure"))), None); + assert_eq!(t.fresh(notice(Some("first failure"))), None); + } + + #[test] + fn only_the_appended_text_is_reported() { + let mut t = NoticeTracker::default(); + t.fresh(notice(Some("first failure"))); + let got = t + .fresh(notice(Some("first failure\nsecond failure"))) + .unwrap(); + assert_eq!(got.detail.as_deref(), Some("second failure")); + // And the buffer keeps growing from there. + let got = t + .fresh(notice(Some("first failure\nsecond failure\nthird"))) + .unwrap(); + assert_eq!(got.detail.as_deref(), Some("third")); + } + + #[test] + fn the_same_failure_twice_is_reported_twice() { + // Accumulation doubles the text, so the second half is new. + let mut t = NoticeTracker::default(); + t.fresh(notice(Some("boom\n"))); + let got = t.fresh(notice(Some("boom\nboom\n"))).unwrap(); + assert_eq!(got.detail.as_deref(), Some("boom\n")); + } + + #[test] + fn unrelated_text_is_reported_whole() { + // If the engine ever stops accumulating, nothing is lost. + let mut t = NoticeTracker::default(); + t.fresh(notice(Some("first failure"))); + let got = t.fresh(notice(Some("a different failure"))).unwrap(); + assert_eq!(got.detail.as_deref(), Some("a different failure")); + } + + #[test] + fn a_notice_without_detail_passes_through() { + let mut t = NoticeTracker::default(); + assert_eq!(t.fresh(notice(None)), Some(notice(None))); + assert_eq!(t.fresh(notice(None)), Some(notice(None))); + } + + #[test] + fn result_set_finds_columns_by_name() { + let rs = ResultSet { + columns: vec!["name".into(), "version".into()], + ..ResultSet::default() + }; + assert_eq!(rs.column("version"), Some(1)); + assert_eq!(rs.column("missing"), None); + } + + #[test] + fn events_serialise_in_the_shape_the_webview_expects() { + let event = QueryEvent::StatementFinished { + index: 0, + row_count: 3, + elapsed_ms: 12, + }; + assert_eq!( + serde_json::to_value(&event).unwrap(), + serde_json::json!({ + "event": "statementFinished", + "data": { "index": 0, "rowCount": 3, "elapsedMs": 12 } + }) + ); + + let event = QueryEvent::Rows { + index: 1, + rows: vec![vec![Some("a".into()), None]], + }; + assert_eq!( + serde_json::to_value(&event).unwrap(), + serde_json::json!({ "event": "rows", "data": { "index": 1, "rows": [["a", null]] } }) + ); + } + + #[test] + fn errors_serialise_with_camel_case_fields() { + let err = QueryError::from_server("ERROR", "XXUUU", "query returns error: nope"); + assert_eq!( + serde_json::to_value(&err).unwrap(), + serde_json::json!({ + "severity": "ERROR", + "code": "XXUUU", + "message": "query returns error: nope", + "connectionLost": false + }) + ); + } +} diff --git a/src-tauri/src/query/session.rs b/src-tauri/src/query/session.rs new file mode 100644 index 0000000..3637f5b --- /dev/null +++ b/src-tauri/src/query/session.rs @@ -0,0 +1,185 @@ +//! One pg wire connection to the engine. +//! +//! Simple query protocol only. See `docs/spike-pgwire.md` for why: the +//! extended protocol does not work through `tokio-postgres` against this +//! server. + +use std::time::Duration; + +use futures_util::StreamExt; +use tokio::sync::mpsc; +use tokio::task::JoinHandle; +use tokio_postgres::config::SslMode; +use tokio_postgres::{AsyncMessage, Client, Config, NoTls, SimpleQueryMessage}; + +use super::result::{Batcher, Notice, NoticeTracker, QueryError, ResultSet, Row}; + +/// How long one connect attempt may take. On Windows a connect to a loopback +/// port that is not listening yet is retried inside the OS for about half a +/// second, so each attempt needs its own limit. +const CONNECT_TIMEOUT: Duration = Duration::from_millis(1500); + +/// What a statement produces while it runs. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum StatementEvent { + Columns(Vec), + Rows(Vec), + Notice(Notice), +} + +pub struct PgSession { + client: Client, + notices: mpsc::UnboundedReceiver, + tracker: NoticeTracker, + driver: JoinHandle<()>, +} + +impl PgSession { + /// Connects to the engine on loopback. The server asks for no password + /// and offers no TLS. + pub async fn connect(port: u16) -> Result { + Self::connect_with_timeout(port, CONNECT_TIMEOUT).await + } + + pub async fn connect_with_timeout(port: u16, limit: Duration) -> Result { + let mut config = Config::new(); + config + .host("127.0.0.1") + .port(port) + .user("stackql") + .dbname("stackql") + .application_name("stackql-workbench") + .ssl_mode(SslMode::Disable); + + let (client, mut connection) = tokio::time::timeout(limit, config.connect(NoTls)) + .await + .map_err(|_| QueryError::from_client("Timed out connecting to the engine.", true))? + .map_err(|err| { + QueryError::from_client(format!("Could not connect to the engine: {err}"), true) + })?; + + // The connection has to be polled for anything to happen. Polling it + // through poll_message, not as a plain future, is what exposes + // notices. + let (tx, notices) = mpsc::unbounded_channel(); + let driver = tokio::spawn(async move { + let mut messages = futures_util::stream::poll_fn(move |cx| connection.poll_message(cx)); + while let Some(message) = messages.next().await { + match message { + Ok(AsyncMessage::Notice(notice)) => { + let _ = tx.send(Notice { + severity: notice.severity().to_string(), + code: notice.code().code().to_string(), + message: notice.message().to_string(), + detail: notice.detail().map(str::to_string), + }); + } + Ok(_) => {} + Err(_) => break, + } + } + }); + + Ok(Self { + client, + notices, + tracker: NoticeTracker::default(), + driver, + }) + } + + pub fn is_closed(&self) -> bool { + self.client.is_closed() + } + + /// Runs one statement and reports what it produces through `sink`. + /// Returns the number of rows. + /// + /// Send exactly one statement. The engine ignores anything after the + /// first statement in a message. + pub async fn run( + &mut self, + sql: &str, + sink: &mut (dyn FnMut(StatementEvent) + Send), + ) -> Result { + let outcome = self.run_inner(sql, sink).await; + // Notices are delivered on the connection before the statement's + // final message, so by now they are all in the channel. + while let Ok(notice) = self.notices.try_recv() { + if let Some(fresh) = self.tracker.fresh(notice) { + sink(StatementEvent::Notice(fresh)); + } + } + outcome + } + + async fn run_inner( + &mut self, + sql: &str, + sink: &mut (dyn FnMut(StatementEvent) + Send), + ) -> Result { + let stream = self + .client + .simple_query_raw(sql) + .await + .map_err(|err| map_error(&err))?; + let mut stream = std::pin::pin!(stream); + let mut batcher = Batcher::default(); + + while let Some(message) = stream.next().await { + match message.map_err(|err| map_error(&err))? { + SimpleQueryMessage::RowDescription(columns) => { + sink(StatementEvent::Columns( + columns.iter().map(|c| c.name().to_string()).collect(), + )); + } + SimpleQueryMessage::Row(row) => { + let mut values = Row::with_capacity(row.len()); + for index in 0..row.len() { + let value = row.try_get(index).map_err(|err| map_error(&err))?; + values.push(value.map(str::to_string)); + } + if let Some(batch) = batcher.push(values) { + sink(StatementEvent::Rows(batch)); + } + } + // The tag is "OK" with no count, so there is nothing to read + // from it. Rows are counted by the batcher. + _ => {} + } + } + + if let Some(batch) = batcher.finish() { + sink(StatementEvent::Rows(batch)); + } + Ok(batcher.total()) + } + + /// Runs one statement and holds the whole result in memory. For metadata + /// statements, which are small. + pub async fn fetch(&mut self, sql: &str) -> Result { + let mut result = ResultSet::default(); + let mut sink = |event: StatementEvent| match event { + StatementEvent::Columns(columns) => result.columns = columns, + StatementEvent::Rows(mut rows) => result.rows.append(&mut rows), + StatementEvent::Notice(notice) => result.notices.push(notice), + }; + self.run(sql, &mut sink).await?; + Ok(result) + } +} + +impl Drop for PgSession { + fn drop(&mut self) { + // Close the socket now, even if a statement is still in flight. The + // engine has no cancel and will finish the statement regardless. + self.driver.abort(); + } +} + +fn map_error(err: &tokio_postgres::Error) -> QueryError { + match err.as_db_error() { + Some(db) => QueryError::from_server(db.severity(), db.code().code(), db.message()), + None => QueryError::from_client(err.to_string(), err.is_closed()), + } +} diff --git a/src-tauri/src/query/split.rs b/src-tauri/src/query/split.rs new file mode 100644 index 0000000..24050fa --- /dev/null +++ b/src-tauri/src/query/split.rs @@ -0,0 +1,201 @@ +//! Splitting editor text into statements. +//! +//! `stackql srv` runs only the first statement of a simple query message and +//! drops the rest without an error (see `docs/spike-pgwire.md`). The host +//! therefore splits the text itself and sends one statement per message. + +/// Splits SQL text on semicolons that are not inside a string, a quoted +/// identifier or a comment. Statements are trimmed. Pieces that hold nothing +/// but whitespace and comments are dropped. +pub fn split_statements(input: &str) -> Vec { + #[derive(Clone, Copy, PartialEq)] + enum State { + Normal, + SingleQuote, + DoubleQuote, + LineComment, + BlockComment, + } + + let mut out = Vec::new(); + let mut current = String::new(); + let mut has_content = false; + let mut state = State::Normal; + let mut chars = input.chars().peekable(); + + while let Some(c) = chars.next() { + match state { + State::Normal => match c { + ';' => { + if has_content { + out.push(current.trim().to_string()); + } + current.clear(); + has_content = false; + continue; + } + '\'' => { + state = State::SingleQuote; + has_content = true; + } + '"' => { + state = State::DoubleQuote; + has_content = true; + } + '-' if chars.peek() == Some(&'-') => state = State::LineComment, + '/' if chars.peek() == Some(&'*') => { + current.push(c); + if let Some(star) = chars.next() { + current.push(star); + } + state = State::BlockComment; + continue; + } + c if !c.is_whitespace() => has_content = true, + _ => {} + }, + // A doubled quote is an escaped quote and stays inside the literal. + State::SingleQuote if c == '\'' => { + if chars.peek() == Some(&'\'') { + current.push(c); + if let Some(next) = chars.next() { + current.push(next); + } + continue; + } + state = State::Normal; + } + State::DoubleQuote if c == '"' => { + if chars.peek() == Some(&'"') { + current.push(c); + if let Some(next) = chars.next() { + current.push(next); + } + continue; + } + state = State::Normal; + } + State::LineComment if c == '\n' => state = State::Normal, + State::BlockComment if c == '*' && chars.peek() == Some(&'/') => { + current.push(c); + if let Some(slash) = chars.next() { + current.push(slash); + } + state = State::Normal; + continue; + } + _ => {} + } + current.push(c); + } + + if has_content { + out.push(current.trim().to_string()); + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_single_statement_is_returned_trimmed() { + assert_eq!( + split_statements(" SHOW PROVIDERS "), + vec!["SHOW PROVIDERS"] + ); + assert_eq!(split_statements("SHOW PROVIDERS;"), vec!["SHOW PROVIDERS"]); + } + + #[test] + fn statements_are_split_on_semicolons() { + assert_eq!( + split_statements("SHOW VERSION; SHOW PROVIDERS;\nSELECT 1"), + vec!["SHOW VERSION", "SHOW PROVIDERS", "SELECT 1"] + ); + } + + #[test] + fn empty_pieces_are_dropped() { + assert_eq!(split_statements(""), Vec::::new()); + assert_eq!(split_statements(" ;; ; "), Vec::::new()); + assert_eq!( + split_statements("SELECT 1;;SELECT 2"), + vec!["SELECT 1", "SELECT 2"] + ); + } + + #[test] + fn semicolons_in_string_literals_do_not_split() { + assert_eq!( + split_statements("SELECT 'a;b' AS x; SELECT 2"), + vec!["SELECT 'a;b' AS x", "SELECT 2"] + ); + } + + #[test] + fn escaped_quotes_stay_inside_the_literal() { + assert_eq!( + split_statements("SELECT 'it''s; fine' AS x; SELECT 2"), + vec!["SELECT 'it''s; fine' AS x", "SELECT 2"] + ); + } + + #[test] + fn semicolons_in_quoted_identifiers_do_not_split() { + assert_eq!( + split_statements("SELECT \"odd;name\" FROM t; SELECT 2"), + vec!["SELECT \"odd;name\" FROM t", "SELECT 2"] + ); + } + + #[test] + fn semicolons_in_comments_do_not_split() { + assert_eq!( + split_statements("SELECT 1 -- not; a split\n; SELECT 2 /* nor; this */;"), + vec!["SELECT 1 -- not; a split", "SELECT 2 /* nor; this */"] + ); + } + + #[test] + fn comment_only_pieces_are_dropped() { + assert_eq!( + split_statements("-- just a note\n; /* another */ ; SELECT 1"), + vec!["SELECT 1"] + ); + assert_eq!(split_statements("-- nothing here"), Vec::::new()); + } + + #[test] + fn a_leading_comment_stays_with_its_statement() { + assert_eq!( + split_statements("-- list them\nSHOW PROVIDERS;"), + vec!["-- list them\nSHOW PROVIDERS"] + ); + } + + #[test] + fn a_quote_inside_a_comment_does_not_open_a_string() { + assert_eq!( + split_statements("SELECT 1 -- don't worry\n; SELECT 2"), + vec!["SELECT 1 -- don't worry", "SELECT 2"] + ); + } + + #[test] + fn an_unterminated_string_keeps_the_rest_together() { + assert_eq!( + split_statements("SELECT 'open; SELECT 2"), + vec!["SELECT 'open; SELECT 2"] + ); + } + + #[test] + fn minus_and_slash_operators_are_not_comments() { + assert_eq!( + split_statements("SELECT 4 - 2 AS a, 4 / 2 AS b; SELECT 1"), + vec!["SELECT 4 - 2 AS a, 4 / 2 AS b", "SELECT 1"] + ); + } +} diff --git a/src-tauri/src/secrets/mod.rs b/src-tauri/src/secrets/mod.rs new file mode 100644 index 0000000..a8faea6 --- /dev/null +++ b/src-tauri/src/secrets/mod.rs @@ -0,0 +1,163 @@ +//! API keys and tokens, kept in the OS keychain. +//! +//! Secrets never go into settings files, logs, the webview or `localStorage`. +//! The webview can ask whether a secret is set and can replace or remove it. +//! It can never read one back. + +use std::collections::HashMap; +use std::sync::Mutex; + +use crate::error::{HostError, HostResult}; +use crate::util::lock; + +/// The keychain service name every entry is stored under. +const SERVICE: &str = "io.stackql.workbench"; + +pub trait SecretStore: Send + Sync { + /// Reads a secret. `None` means it has never been set. + fn get(&self, name: &str) -> HostResult>; + fn set(&self, name: &str, value: &str) -> HostResult<()>; + /// Removes a secret. Removing one that is not there is not an error. + fn delete(&self, name: &str) -> HostResult<()>; +} + +/// The OS keychain: Credential Manager on Windows, Keychain on macOS. +pub struct KeychainStore { + _private: (), +} + +impl KeychainStore { + /// Installs the platform credential store and returns a handle to it. + pub fn open() -> HostResult { + install_platform_store()?; + Ok(Self { _private: () }) + } + + fn entry(name: &str) -> HostResult { + keyring_core::Entry::new(SERVICE, name).map_err(|err| fail("open", name, &err)) + } +} + +#[cfg(windows)] +fn install_platform_store() -> HostResult<()> { + let store = windows_native_keyring_store::Store::new() + .map_err(|err| HostError::Secrets(format!("Could not open Credential Manager: {err}")))?; + keyring_core::set_default_store(store); + Ok(()) +} + +#[cfg(target_os = "macos")] +fn install_platform_store() -> HostResult<()> { + let store = apple_native_keyring_store::keychain::Store::new() + .map_err(|err| HostError::Secrets(format!("Could not open the Keychain: {err}")))?; + keyring_core::set_default_store(store); + Ok(()) +} + +#[cfg(not(any(windows, target_os = "macos")))] +fn install_platform_store() -> HostResult<()> { + Err(HostError::Secrets( + "No OS keychain is available on this platform.".to_string(), + )) +} + +/// Builds an error that names the secret but never includes its value. +fn fail(action: &str, name: &str, err: &dyn std::fmt::Display) -> HostError { + HostError::Secrets(format!( + "Could not {action} '{name}' in the OS keychain: {err}" + )) +} + +impl SecretStore for KeychainStore { + fn get(&self, name: &str) -> HostResult> { + match Self::entry(name)?.get_password() { + Ok(value) => Ok(Some(value)), + Err(keyring_core::Error::NoEntry) => Ok(None), + Err(err) => Err(fail("read", name, &err)), + } + } + + fn set(&self, name: &str, value: &str) -> HostResult<()> { + Self::entry(name)? + .set_password(value) + .map_err(|err| fail("store", name, &err)) + } + + fn delete(&self, name: &str) -> HostResult<()> { + match Self::entry(name)?.delete_credential() { + Ok(()) | Err(keyring_core::Error::NoEntry) => Ok(()), + Err(err) => Err(fail("remove", name, &err)), + } + } +} + +/// Keeps secrets in memory. For tests, and as the fallback when the OS +/// keychain cannot be opened, in which case a key lasts until the app closes. +#[derive(Default)] +pub struct MemoryStore { + values: Mutex>, +} + +impl SecretStore for MemoryStore { + fn get(&self, name: &str) -> HostResult> { + Ok(lock(&self.values).get(name).cloned()) + } + + fn set(&self, name: &str, value: &str) -> HostResult<()> { + lock(&self.values).insert(name.to_string(), value.to_string()); + Ok(()) + } + + fn delete(&self, name: &str) -> HostResult<()> { + lock(&self.values).remove(name); + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn memory_store_round_trips() { + let store = MemoryStore::default(); + assert_eq!(store.get("k").unwrap(), None); + store.set("k", "v1").unwrap(); + assert_eq!(store.get("k").unwrap().as_deref(), Some("v1")); + store.set("k", "v2").unwrap(); + assert_eq!(store.get("k").unwrap().as_deref(), Some("v2")); + store.delete("k").unwrap(); + assert_eq!(store.get("k").unwrap(), None); + // Removing something that is not there is fine. + store.delete("k").unwrap(); + } + + #[test] + fn errors_name_the_secret_but_never_carry_a_value() { + let err = fail("store", "inference.gemini.api_key", &"access denied"); + let text = err.to_string(); + assert!(text.contains("inference.gemini.api_key")); + assert!(text.contains("access denied")); + } + + /// Exercises the real OS keychain. It writes and removes one throwaway + /// entry. Skipped where the keychain cannot be opened, for example on a + /// headless build machine. + #[test] + fn os_keychain_round_trips() { + let Ok(store) = KeychainStore::open() else { + eprintln!("skipped: no OS keychain available"); + return; + }; + let name = format!("test.round_trip.{}", std::process::id()); + let value = "not-a-real-secret"; + if store.set(&name, value).is_err() { + eprintln!("skipped: the OS keychain refused a write"); + return; + } + assert_eq!(store.get(&name).unwrap().as_deref(), Some(value)); + store.delete(&name).unwrap(); + assert_eq!(store.get(&name).unwrap(), None); + store.delete(&name).unwrap(); + } +} diff --git a/src-tauri/src/util.rs b/src-tauri/src/util.rs new file mode 100644 index 0000000..9facb21 --- /dev/null +++ b/src-tauri/src/util.rs @@ -0,0 +1,34 @@ +//! Small shared helpers. + +use std::sync::{Mutex, MutexGuard, PoisonError}; + +/// Locks a mutex, recovering the guard if another thread panicked while +/// holding it. The data guarded in this crate stays consistent across a +/// panic, so poisoning carries no information worth failing on. +pub fn lock(mutex: &Mutex) -> MutexGuard<'_, T> { + mutex.lock().unwrap_or_else(PoisonError::into_inner) +} + +/// Shortens text for logs and status lines without splitting a character. +pub fn truncate(text: &str, max_chars: usize) -> String { + if text.chars().count() <= max_chars { + return text.to_string(); + } + let head: String = text.chars().take(max_chars).collect(); + format!("{head}...") +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn truncate_keeps_short_text() { + assert_eq!(truncate("abc", 5), "abc"); + } + + #[test] + fn truncate_cuts_on_a_character_boundary() { + assert_eq!(truncate("héllo wörld", 4), "héll..."); + } +} diff --git a/src-tauri/src/webview_runtime.rs b/src-tauri/src/webview_runtime.rs new file mode 100644 index 0000000..0e33e62 --- /dev/null +++ b/src-tauri/src/webview_runtime.rs @@ -0,0 +1,284 @@ +//! The page renderer on Windows, and using one that ships with the app. +//! +//! The window is drawn by Microsoft's WebView2 runtime. It is not part of +//! the executable and cannot be: it is a browser engine of several hundred +//! megabytes. Windows 11 has it built in, and Windows 10 gets it with Edge, +//! but it is still something the system has to supply. +//! +//! An installer that wants the app to stand on its own puts Microsoft's +//! Fixed Version runtime in a folder beside the executable. When that folder +//! is there the app uses it and never looks at what the system has. When it +//! is not, the system's runtime is used, as before. Nothing is configured: +//! the folder being there is the whole switch. +//! +//! macOS has no such thing to ship. Its renderer is part of the system. +//! +//! Where no runtime can be found there is no window to say so in. The app +//! checks before it starts anything, and says it in a dialog of the system's +//! own, with the address of Microsoft's page for the runtime. The installers +//! are left out of it: they neither ship the runtime nor install it. + +use std::path::{Path, PathBuf}; + +/// The folder beside the executable that holds a runtime shipped with the +/// app. Microsoft's own name for the folder carries a version and an +/// architecture, so an installer renames it to this. +pub const FOLDER_NAME: &str = "WebView2Runtime"; + +/// The program every WebView2 runtime folder has. Its presence is how a +/// folder is told from an empty or half-copied one. +const RUNTIME_PROGRAM: &str = "msedgewebview2.exe"; + +/// The variable the WebView2 loader reads for a runtime to use in place of +/// the installed one. +pub const FOLDER_VARIABLE: &str = "WEBVIEW2_BROWSER_EXECUTABLE_FOLDER"; + +/// The runtime folder beside an executable, if there is a usable one. +/// `is_file` is injected so tests can describe a file system. +pub fn beside(exe: &Path, is_file: impl Fn(&Path) -> bool) -> Option { + let folder = exe.parent()?.join(FOLDER_NAME); + is_file(&folder.join(RUNTIME_PROGRAM)).then_some(folder) +} + +/// Points the webview at the runtime beside this executable, when there is +/// one, and returns its folder. Does nothing and returns `None` otherwise, +/// and on every platform but Windows. +/// +/// This must be the first thing the program does: the loader reads the +/// variable when the first window is made, and a variable may only be set +/// while no other thread can be reading the environment. +/// +/// A runtime beside the app is used even if the variable was already set. +/// What shipped with the app is what the app was tested with, which is the +/// same rule the engine follows. +pub fn use_bundled() -> Option { + #[cfg(windows)] + { + let exe = std::env::current_exe().ok()?; + let folder = beside(&exe, |path| path.is_file())?; + // SAFETY: called from `run` before anything else, so no other thread + // exists yet that could read or write the environment. + unsafe { std::env::set_var(FOLDER_VARIABLE, &folder) }; + Some(folder) + } + #[cfg(not(windows))] + { + None + } +} + +/// Microsoft's page for the runtime, where it is downloaded from. It is the +/// one address the dialog below opens, and it is held here: what the dialog +/// passes back on a click is not used. +pub const DOWNLOAD_PAGE: &str = "https://developer.microsoft.com/en-us/microsoft-edge/webview2/"; + +/// The line the dialog leads with when no runtime can be found. +pub const NOTICE_HEADING: &str = "StackQL Workbench requires the Microsoft Edge WebView2 Runtime"; + +/// What follows the heading, as plain text with the address spelled out. +/// +/// It is this one sentence and no more. The maintainer asked for that: the +/// operator needs to know what is missing and where to get it, not what the +/// runtime is for or where it was looked for. +pub fn notice_body() -> String { + format!("See {DOWNLOAD_PAGE} for installation instructions.") +} + +/// The body with the address marked as a link, in the form a task dialog +/// reads. +pub fn notice_markup() -> String { + let link = format!("{DOWNLOAD_PAGE}"); + notice_body().replacen(DOWNLOAD_PAGE, &link, 1) +} + +/// Stops the app, with a dialog that says why, when no page renderer can be +/// found. Does nothing where one is found, and on every platform but +/// Windows, where the renderer is part of the system. +/// +/// Call it after [`use_bundled`] and before anything else is started. The +/// question asked is the one Tauri asks before it makes a window, so this +/// never stops an app that would have run. Without it the app would end in +/// a panic, behind a dialog of Tauri's that names no app. +/// +/// The notice is the same whatever the reason no runtime could be used, a +/// folder beside the app that holds a broken one included. +pub fn require() { + #[cfg(windows)] + if tauri::webview_version().is_err() { + dialog::show(); + std::process::exit(1); + } +} + +/// The dialog, drawn by Windows. No part of the app is running yet. +#[cfg(windows)] +mod dialog { + use std::ffi::OsStr; + use std::os::windows::ffi::OsStrExt; + use std::ptr; + + use windows_sys::Win32::Foundation::{HWND, LPARAM, WPARAM}; + use windows_sys::Win32::UI::Controls::{ + TASKDIALOGCONFIG, TASKDIALOGCONFIG_0, TD_INFORMATION_ICON, TDCBF_CLOSE_BUTTON, + TDF_ALLOW_DIALOG_CANCELLATION, TDF_ENABLE_HYPERLINKS, TDN_HYPERLINK_CLICKED, + TaskDialogIndirect, + }; + use windows_sys::core::HRESULT; + + use super::{DOWNLOAD_PAGE, NOTICE_HEADING, notice_body, notice_markup}; + + const TITLE: &str = "StackQL Workbench"; + + /// The width of the dialog, in the units Windows lays dialogs out in, + /// which grow with the size of the system's text. + const WIDTH: u32 = 360; + + /// Text as Windows takes it: UTF-16 with a zero at the end. + fn wide(text: &str) -> Vec { + OsStr::new(text) + .encode_wide() + .chain(std::iter::once(0)) + .collect() + } + + /// Told by the dialog what happens in it. A click on the link opens the + /// download page in the operator's browser. The address opened is the + /// one this module holds, whatever the dialog passes. + extern "system" fn on_event( + _window: HWND, + event: u32, + _wparam: WPARAM, + _lparam: LPARAM, + _data: isize, + ) -> HRESULT { + if i32::try_from(event) == Ok(TDN_HYPERLINK_CLICKED) { + // Nothing can be said if this fails: the address is in the text. + let _ = tauri_plugin_opener::open_url(DOWNLOAD_PAGE, None::<&str>); + } + 0 + } + + /// Shows the notice and returns when the operator closes it. + pub fn show() { + let title = wide(TITLE); + let heading = wide(NOTICE_HEADING); + let content = wide(¬ice_markup()); + let config = TASKDIALOGCONFIG { + cbSize: u32::try_from(size_of::()).unwrap_or(0), + dwFlags: TDF_ENABLE_HYPERLINKS | TDF_ALLOW_DIALOG_CANCELLATION, + // Wide enough for the sentence to sit on one line. At the usual + // width the address is broken in two. + cxWidth: WIDTH, + dwCommonButtons: TDCBF_CLOSE_BUTTON, + pszWindowTitle: title.as_ptr(), + Anonymous1: TASKDIALOGCONFIG_0 { + pszMainIcon: TD_INFORMATION_ICON, + }, + pszMainInstruction: heading.as_ptr(), + pszContent: content.as_ptr(), + pfCallback: Some(on_event), + ..Default::default() + }; + // SAFETY: `config` is a live struct of the size it states. Every + // pointer in it is to a zero-ended buffer that outlives the call, or + // is one of the system's own icon ids. The three places for results + // may be null, which asks for none. The call returns only when the + // dialog has closed, so the callback is not called after it. + let outcome = unsafe { + TaskDialogIndirect(&config, ptr::null_mut(), ptr::null_mut(), ptr::null_mut()) + }; + if outcome < 0 { + // No dialog could be shown. A console, if there is one, is the + // only place left to say it. + eprintln!("{NOTICE_HEADING}\n{}", notice_body()); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_notice_says_what_is_needed_and_where_to_get_it() { + assert_eq!( + NOTICE_HEADING, + "StackQL Workbench requires the Microsoft Edge WebView2 Runtime" + ); + assert_eq!( + notice_body(), + "See https://developer.microsoft.com/en-us/microsoft-edge/webview2/ \ + for installation instructions." + ); + } + + #[test] + fn the_notice_is_one_short_sentence_of_plain_text() { + // It says what is missing and where to get it. What the runtime is + // for, and where it was looked for, are left out on purpose. + let body = notice_body(); + assert!(body.len() < 110, "{}", body.len()); + assert!(!body.contains('\n')); + assert_eq!(body.matches(". ").count(), 0); + assert!(body.is_ascii()); + assert!(NOTICE_HEADING.is_ascii()); + assert!(!body.contains('<')); + } + + #[test] + fn the_address_is_microsofts_and_is_given_once() { + assert!(DOWNLOAD_PAGE.starts_with("https://developer.microsoft.com/")); + assert_eq!(notice_body().matches(DOWNLOAD_PAGE).count(), 1); + assert_eq!(notice_body().matches("https://").count(), 1); + } + + #[test] + fn the_link_in_the_dialog_is_the_address_in_the_text() { + let markup = notice_markup(); + assert_eq!( + markup, + format!( + "See {DOWNLOAD_PAGE} for installation \ + instructions." + ) + ); + assert_eq!(markup.matches("").count(), 1); + } + + #[test] + fn a_runtime_beside_the_app_is_found() { + let exe = Path::new("/apps/StackQL/stackql-workbench.exe"); + let program = Path::new("/apps/StackQL") + .join(FOLDER_NAME) + .join(RUNTIME_PROGRAM); + let found = beside(exe, |path| path == program); + assert_eq!(found, Some(Path::new("/apps/StackQL").join(FOLDER_NAME))); + } + + #[test] + fn no_folder_means_the_system_runtime() { + let exe = Path::new("/apps/StackQL/stackql-workbench.exe"); + assert_eq!(beside(exe, |_| false), None); + } + + #[test] + fn a_folder_without_the_runtime_program_is_not_a_runtime() { + // An empty folder, or one a copy did not finish, must not be handed + // to the loader: it would fail where the system's runtime works. + let exe = Path::new("/apps/StackQL/stackql-workbench.exe"); + let stray = Path::new("/apps/StackQL") + .join(FOLDER_NAME) + .join("readme.txt"); + assert_eq!(beside(exe, |path| path == stray), None); + } + + #[test] + fn a_runtime_somewhere_else_is_not_this_apps() { + let exe = Path::new("/apps/StackQL/stackql-workbench.exe"); + let elsewhere = Path::new("/apps/Other") + .join(FOLDER_NAME) + .join(RUNTIME_PROGRAM); + assert_eq!(beside(exe, |path| path == elsewhere), None); + } +} diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json new file mode 100644 index 0000000..9db665c --- /dev/null +++ b/src-tauri/tauri.conf.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://schema.tauri.app/config/2", + "productName": "StackQL Workbench", + "mainBinaryName": "stackql-workbench", + "version": "0.1.0", + "identifier": "io.stackql.workbench", + "build": { + "beforeDevCommand": "npm run dev", + "devUrl": "http://127.0.0.1:5173", + "beforeBuildCommand": "npm run build", + "frontendDist": "../dist", + "windows": { + "staticVCRuntime": false + } + }, + "app": { + "windows": [ + { + "label": "main", + "title": "StackQL Workbench", + "width": 1360, + "height": 860, + "minWidth": 960, + "minHeight": 600 + } + ], + "security": { + "csp": { + "default-src": "'self'", + "script-src": "'self'", + "style-src": "'self' 'unsafe-inline'", + "img-src": "'self' data:", + "font-src": "'self' data:", + "connect-src": "ipc: http://ipc.localhost" + } + } + }, + "bundle": { + "active": true, + "targets": "all", + "macOS": { + "minimumSystemVersion": "13.0" + }, + "icon": [ + "icons/32x32.png", + "icons/128x128.png", + "icons/128x128@2x.png", + "icons/icon.icns", + "icons/icon.ico" + ] + } +} diff --git a/src-tauri/tests/agent_integration.rs b/src-tauri/tests/agent_integration.rs new file mode 100644 index 0000000..f80cc67 --- /dev/null +++ b/src-tauri/tests/agent_integration.rs @@ -0,0 +1,818 @@ +//! The agent loop against a real `stackql mcp`, with a scripted stand-in for +//! the model. +//! +//! No inference provider is called and no API key is needed: the "model" +//! here replies from a script. Everything else is real: the engine process, +//! the MCP session, the tool calls, the approval prompts and the audit log. +//! +//! Skipped, with a note on stderr, when no `stackql` binary can be found. +//! No cloud credentials and no network are needed. The one mutation that is +//! sent is never approved. + +use std::collections::VecDeque; +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use futures_util::FutureExt; +use futures_util::future::BoxFuture; +use serde_json::{Map, Value, json}; +use stackql_workbench_lib::activity::read_audit; +use stackql_workbench_lib::agent::approvals::ApprovalDecision; +use stackql_workbench_lib::agent::backend::{ + ChatRequest, ChatResponse, InferenceBackend, InferenceError, Message, StopReason, ToolCall, + Usage, +}; +use stackql_workbench_lib::agent::runtime::{AgentEvent, AgentRuntime, Emit}; +use stackql_workbench_lib::config::{Settings, SettingsStore}; +use stackql_workbench_lib::connection::local::LocalConnection; +use stackql_workbench_lib::connection::{Connection, EngineState, SafetyMode}; +use stackql_workbench_lib::engine::approot::Defaults as ApprootDefaults; +use stackql_workbench_lib::engine::discovery::{self, Inputs}; + +const DELETE_SQL: &str = + "DELETE FROM github.repos.repos WHERE owner = 'nobody-xyz' AND repo = 'nothing-xyz'"; + +fn engine_available() -> bool { + let found = discovery::resolve(&Inputs::from_environment(None), |p| p.is_file()).is_ok(); + if !found { + eprintln!("skipped: no stackql binary found (set STACKQL_BIN or add stackql to PATH)"); + } + found +} + +/// What the scripted model was sent on one call. +#[derive(Clone)] +struct Seen { + system: String, + messages: Vec, + tool_names: Vec, +} + +/// A model that replies from a script and remembers what it was asked. +struct Scripted { + replies: Mutex>, + seen: Mutex>, +} + +impl Scripted { + fn new(replies: Vec) -> Arc { + Arc::new(Self { + replies: Mutex::new(replies.into()), + seen: Mutex::new(Vec::new()), + }) + } + + fn seen(&self) -> Vec { + self.seen.lock().unwrap().clone() + } +} + +impl InferenceBackend for Scripted { + fn complete<'a>( + &'a self, + request: ChatRequest<'a>, + ) -> BoxFuture<'a, Result> { + self.seen.lock().unwrap().push(Seen { + system: request.system.to_string(), + messages: request.messages.to_vec(), + tool_names: request.tools.iter().map(|t| t.name.clone()).collect(), + }); + let reply = self.replies.lock().unwrap().pop_front(); + async move { reply.ok_or_else(|| InferenceError::Protocol("the script ran out".into())) } + .boxed() + } +} + +fn calls(calls: &[(&str, &str, Value)]) -> ChatResponse { + ChatResponse { + text: String::new(), + tool_calls: calls + .iter() + .map(|(id, name, args)| ToolCall { + id: (*id).to_string(), + name: (*name).to_string(), + arguments: args.as_object().cloned().unwrap_or_else(Map::new), + }) + .collect(), + raw: None, + stop: StopReason::ToolUse, + usage: Usage { + input_tokens: Some(100), + output_tokens: Some(10), + cached_input_tokens: None, + }, + } +} + +fn says(text: &str) -> ChatResponse { + ChatResponse { + text: text.to_string(), + tool_calls: Vec::new(), + raw: None, + stop: StopReason::EndTurn, + usage: Usage { + input_tokens: Some(200), + output_tokens: Some(20), + cached_input_tokens: Some(150), + }, + } +} + +struct Fixture { + connection: Arc, + runtime: Arc, + approot: PathBuf, +} + +async fn fixture(name: &str) -> Fixture { + let approot = std::env::temp_dir().join(format!("wb-agent-it-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&approot); + let settings = Arc::new(SettingsStore::in_memory(Settings::default())); + let connection = Arc::new( + LocalConnection::new( + ApprootDefaults::fixed(approot.clone()), + approot.join("audit"), + settings, + ) + .unwrap(), + ); + let status = connection.start().await; + assert_eq!( + status.state, + EngineState::Running, + "engine did not start: {:?}", + status.error + ); + let runtime = Arc::new(AgentRuntime::new(connection.clone())); + Fixture { + connection, + runtime, + approot, + } +} + +async fn teardown(fixture: Fixture) { + fixture.runtime.reset().await; + fixture.connection.shutdown().await; + let _ = std::fs::remove_dir_all(fixture.approot); +} + +fn collector() -> (Emit, Arc>>) { + let events: Arc>> = Arc::default(); + let sink = events.clone(); + let emit: Emit = Arc::new(move |event| sink.lock().unwrap().push(event)); + (emit, events) +} + +/// Collects events and answers every approval prompt with `decision`, the +/// way the operator would by pressing a button. +fn answering( + runtime: &Arc, + decision: ApprovalDecision, +) -> (Emit, Arc>>) { + let events: Arc>> = Arc::default(); + let sink = events.clone(); + let runtime = runtime.clone(); + let emit: Emit = Arc::new(move |event| { + if let AgentEvent::ApprovalRequested { request } = &event { + let runtime = runtime.clone(); + let id = request.id.clone(); + tokio::spawn(async move { + tokio::time::sleep(Duration::from_millis(40)).await; + runtime.approvals().resolve(&id, decision); + }); + } + sink.lock().unwrap().push(event); + }); + (emit, events) +} + +fn tool_results(seen: &Seen) -> Vec<(String, bool)> { + seen.messages + .iter() + .filter_map(|m| match m { + Message::ToolResults { results } => Some(results), + _ => None, + }) + .flatten() + .map(|r| (r.content.clone(), r.is_error)) + .collect() +} + +#[tokio::test] +async fn a_turn_runs_tools_through_the_engine_and_feeds_the_results_back() { + if !engine_available() { + return; + } + let fx = fixture("tools").await; + let model = Scripted::new(vec![ + calls(&[ + ("c1", "list_providers", json!({})), + ( + "c2", + "run_select_query", + json!({ "sql": "SELECT 1 AS one" }), + ), + ]), + says("There is one provider installed."), + ]); + let (emit, events) = collector(); + + let summary = fx + .runtime + .send( + model.clone(), + SafetyMode::Safe, + "what is installed?".into(), + emit, + ) + .await + .unwrap(); + + assert_eq!(summary.steps, 2); + assert_eq!(summary.tool_calls, 2); + assert!(!summary.stopped); + assert_eq!(summary.stop, StopReason::EndTurn); + // Two calls to the model: one that asked for a tool, one that answered. + assert_eq!(summary.usage.input_tokens, Some(300)); + assert_eq!(summary.usage.output_tokens, Some(30)); + assert_eq!(summary.usage.cached_input_tokens, Some(150)); + + let events = events.lock().unwrap().clone(); + // A session was opened in the requested mode, on a revision with a handshake. + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::SessionStarted { mode: SafetyMode::Safe, protocol_version, tools } + if protocol_version == "2025-11-25" && *tools == 15 + ))); + // The statement is surfaced as SQL before it runs. + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::ToolCallStarted { id, tool, sql: Some(sql), .. } + if id == "c2" && tool == "run_select_query" && sql == "SELECT 1 AS one" + ))); + // Row results come back as a table for the grid. + let providers = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallFinished { + id, + table: Some(table), + is_error: false, + .. + } if id == "c1" => Some(table.clone()), + _ => None, + }) + .expect("list_providers should return a table"); + assert_eq!(providers.columns, vec!["name", "version"]); + assert!( + providers + .rows + .iter() + .any(|row| row[0].as_deref() == Some("stackql_preview")) + ); + let one = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallFinished { + id, + table: Some(table), + .. + } if id == "c2" => Some(table.clone()), + _ => None, + }) + .unwrap(); + assert_eq!(one.rows, vec![vec![Some("1".to_string())]]); + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::AssistantText { text } if text == "There is one provider installed." + ))); + + // What the model was given. + let seen = model.seen(); + assert_eq!(seen.len(), 2); + assert!(seen[0].tool_names.contains(&"run_select_query".to_string())); + assert!( + seen[0] + .tool_names + .contains(&"run_mutation_query".to_string()) + ); + // The engine's own guidance is part of the system prompt. + assert!(seen[0].system.contains("StackQL Workbench")); + assert!(seen[0].system.contains("..")); + assert!( + matches!(&seen[0].messages[..], [Message::User { text }] if text == "what is installed?") + ); + // Both results went back, in one message, before the second call. + let results = tool_results(&seen[1]); + assert_eq!(results.len(), 2); + assert!(results[0].0.contains("stackql_preview")); + assert!(!results[0].1); + + // The engine recorded what the agent did. + let audit = read_audit(&fx.connection.audit_dir().unwrap(), 50); + assert!( + audit + .iter() + .any(|r| r.tool == "list_providers" && r.decision == "allow") + ); + assert!( + audit + .iter() + .any(|r| r.tool == "run_select_query" && r.sql.as_deref() == Some("SELECT 1 AS one")) + ); + + teardown(fx).await; +} + +#[tokio::test] +async fn a_mutation_waits_for_the_operator_and_a_decline_reaches_the_model() { + if !engine_available() { + return; + } + let fx = fixture("decline").await; + let model = Scripted::new(vec![ + calls(&[("c1", "run_mutation_query", json!({ "sql": DELETE_SQL }))]), + says("Understood, I will not delete it."), + ]); + let (emit, events) = answering(&fx.runtime, ApprovalDecision::Decline); + + let summary = fx + .runtime + .send( + model.clone(), + SafetyMode::Safe, + "delete that repo".into(), + emit, + ) + .await + .unwrap(); + assert_eq!(summary.steps, 2); + assert!(!summary.stopped); + + let events = events.lock().unwrap().clone(); + // The card shows the engine's classification and the exact SQL. + let request = events + .iter() + .find_map(|e| match e { + AgentEvent::ApprovalRequested { request } => Some(request.clone()), + _ => None, + }) + .expect("the engine should ask for approval in safe mode"); + assert_eq!(request.tool.as_deref(), Some("run_mutation_query")); + assert_eq!(request.query_class.as_deref(), Some("mutation_delete")); + assert_eq!(request.sql.as_deref(), Some(DELETE_SQL)); + assert!(request.message.contains(DELETE_SQL)); + + // Declined: the tool reports an error and nothing ran. + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::ToolCallFinished { id, is_error: true, text, .. } + if id == "c1" && text.contains("declined") + ))); + let results = tool_results(&model.seen()[1]); + assert_eq!(results.len(), 1); + assert!(results[0].1, "the model must see the refusal as an error"); + assert!(results[0].0.contains("declined")); + + let audit = read_audit(&fx.connection.audit_dir().unwrap(), 50); + assert!(audit.iter().any(|r| { + r.tool == "run_mutation_query" + && r.decision == "needs_approval_declined" + && r.query_class == "mutation_delete" + && r.sql.as_deref() == Some(DELETE_SQL) + })); + + teardown(fx).await; +} + +/// Where in the stream of events a call started. +fn started_at(events: &[AgentEvent], call: &str) -> usize { + events + .iter() + .position(|e| matches!(e, AgentEvent::ToolCallStarted { id, .. } if id == call)) + .unwrap_or_else(|| panic!("{call} never started")) +} + +/// Where in the stream of events a call finished. +fn finished_at(events: &[AgentEvent], call: &str) -> usize { + events + .iter() + .position(|e| matches!(e, AgentEvent::ToolCallFinished { id, .. } if id == call)) + .unwrap_or_else(|| panic!("{call} never finished")) +} + +#[tokio::test] +async fn independent_calls_in_one_reply_run_together_and_answer_in_order() { + if !engine_available() { + return; + } + let fx = fixture("together").await; + let model = Scripted::new(vec![ + calls(&[ + ( + "c1", + "run_select_query", + json!({ "sql": "SELECT 1 AS one" }), + ), + ("c2", "list_providers", json!({})), + ( + "c3", + "run_select_query", + json!({ "sql": "SELECT 2 AS two" }), + ), + ]), + says("All three are in."), + ]); + let (emit, events) = collector(); + + let summary = fx + .runtime + .send( + model.clone(), + SafetyMode::Safe, + "three things at once".into(), + emit, + ) + .await + .unwrap(); + assert_eq!(summary.steps, 2); + assert_eq!(summary.tool_calls, 3); + + // The engine marks all three tools as not destructive, so every call + // was under way before the first of them finished. + let events = events.lock().unwrap().clone(); + let first_done = ["c1", "c2", "c3"] + .iter() + .map(|call| finished_at(&events, call)) + .min() + .unwrap(); + for call in ["c1", "c2", "c3"] { + assert!( + started_at(&events, call) < first_done, + "{call} did not start until another call had finished" + ); + } + + // The model gets one answer per call, in the order it asked. + let results = tool_results(&model.seen()[1]); + assert_eq!(results.len(), 3); + assert!(results.iter().all(|(_, is_error)| !is_error), "{results:?}"); + assert!(results[0].0.contains("one"), "{}", results[0].0); + assert!(results[1].0.contains("stackql_preview"), "{}", results[1].0); + assert!(results[2].0.contains("two"), "{}", results[2].0); + + teardown(fx).await; +} + +#[tokio::test] +async fn a_change_runs_alone_between_the_calls_around_it() { + if !engine_available() { + return; + } + let fx = fixture("ordered").await; + let model = Scripted::new(vec![ + calls(&[ + ( + "c1", + "run_select_query", + json!({ "sql": "SELECT 1 AS one" }), + ), + ("c2", "run_mutation_query", json!({ "sql": DELETE_SQL })), + ( + "c3", + "run_select_query", + json!({ "sql": "SELECT 2 AS two" }), + ), + ]), + says("The delete was declined."), + ]); + let (emit, events) = answering(&fx.runtime, ApprovalDecision::Decline); + + let summary = fx + .runtime + .send( + model.clone(), + SafetyMode::Safe, + "query, delete, query".into(), + emit, + ) + .await + .unwrap(); + assert_eq!(summary.tool_calls, 3); + + // The engine marks the mutation tool as destructive. It waits for what + // came before it, and what comes after waits for it. + let events = events.lock().unwrap().clone(); + assert!(finished_at(&events, "c1") < started_at(&events, "c2")); + assert!(finished_at(&events, "c2") < started_at(&events, "c3")); + + // The prompt was for the change, and the operator's answer stood. + let asked: Vec<_> = events + .iter() + .filter_map(|e| match e { + AgentEvent::ApprovalRequested { request } => Some(request.sql.clone()), + _ => None, + }) + .collect(); + assert_eq!(asked, [Some(DELETE_SQL.to_string())]); + + let results = tool_results(&model.seen()[1]); + assert_eq!(results.len(), 3); + assert!(!results[0].1 && results[0].0.contains("one")); + assert!(results[1].1 && results[1].0.contains("declined")); + assert!(!results[2].1 && results[2].0.contains("two")); + + teardown(fx).await; +} + +/// The values of one column of a tool result shown to the operator. +fn tool_column(events: &[AgentEvent], call: &str, column: &str) -> Vec { + let table = events + .iter() + .find_map(|e| match e { + AgentEvent::ToolCallFinished { + id, + table: Some(table), + .. + } if id == call => Some(table.clone()), + _ => None, + }) + .unwrap_or_else(|| panic!("{call} returned no table")); + let at = table + .columns + .iter() + .position(|c| c == column) + .unwrap_or_else(|| panic!("{call} has no column {column}: {:?}", table.columns)); + let mut values: Vec = table + .rows + .iter() + .filter_map(|row| row[at].clone()) + .collect(); + values.sort(); + values +} + +#[tokio::test] +async fn the_equivalent_sql_shown_for_discovery_tools_returns_what_the_tools_return() { + if !engine_available() { + return; + } + // The webview shows these statements under "Equivalent SQL" on the cards + // of the discovery tools. See src/lib/equivalentSql.ts. This holds the + // claim to the engine: the statement gives the rows the tool gave. + let fx = fixture("equivalent").await; + let model = Scripted::new(vec![ + calls(&[ + ("c1", "list_providers", json!({})), + ( + "c2", + "list_services", + json!({ "provider": "stackql_preview" }), + ), + ]), + says("Listed."), + ]); + let (emit, events) = collector(); + fx.runtime + .send(model, SafetyMode::ReadOnly, "list".into(), emit) + .await + .unwrap(); + let events = events.lock().unwrap().clone(); + + for (call, statement) in [ + ("c1", "SHOW PROVIDERS;"), + ("c2", "SHOW SERVICES IN stackql_preview;"), + ] { + let result = fx.connection.fetch(statement.to_string()).await.unwrap(); + let at = result.column("name").expect("a name column"); + let mut from_statement: Vec = result + .rows + .iter() + .filter_map(|row| row.get(at).cloned().flatten()) + .collect(); + from_statement.sort(); + assert!(!from_statement.is_empty(), "{statement} returned nothing"); + assert_eq!( + tool_column(&events, call, "name"), + from_statement, + "{statement} is not equivalent to the tool" + ); + } + + teardown(fx).await; +} + +#[tokio::test] +async fn read_only_mode_refuses_without_asking() { + if !engine_available() { + return; + } + let fx = fixture("readonly").await; + let model = Scripted::new(vec![ + calls(&[("c1", "run_mutation_query", json!({ "sql": DELETE_SQL }))]), + says("That is not allowed here."), + ]); + let (emit, events) = collector(); + + fx.runtime + .send( + model.clone(), + SafetyMode::ReadOnly, + "delete that repo".into(), + emit, + ) + .await + .unwrap(); + + let events = events.lock().unwrap().clone(); + assert!( + !events + .iter() + .any(|e| matches!(e, AgentEvent::ApprovalRequested { .. })), + "read_only refuses outright, so there is nothing to approve" + ); + assert!(events.iter().any(|e| matches!( + e, + AgentEvent::ToolCallFinished { is_error: true, text, .. } if text.contains("read_only") + ))); + let audit = read_audit(&fx.connection.audit_dir().unwrap(), 50); + assert!( + audit + .iter() + .any(|r| r.mode == "read_only" && r.decision == "refuse_immediate") + ); + + teardown(fx).await; +} + +#[tokio::test] +async fn nothing_is_approved_when_nobody_answers_and_the_turn_is_stopped() { + if !engine_available() { + return; + } + let fx = fixture("stop").await; + let model = Scripted::new(vec![ + calls(&[("c1", "run_mutation_query", json!({ "sql": DELETE_SQL }))]), + // Used by the turn after the stopped one. + says("Still here."), + ]); + + // Nobody answers the prompt. The operator stops the turn instead. + let events: Arc>> = Arc::default(); + let sink = events.clone(); + let stopper = fx.runtime.clone(); + let emit: Emit = Arc::new(move |event| { + if matches!(event, AgentEvent::ApprovalRequested { .. }) { + let stopper = stopper.clone(); + tokio::spawn(async move { + tokio::time::sleep(Duration::from_millis(150)).await; + assert!(stopper.stop(), "a turn should be running"); + }); + } + sink.lock().unwrap().push(event); + }); + + let summary = tokio::time::timeout( + Duration::from_secs(20), + fx.runtime.send( + model.clone(), + SafetyMode::Safe, + "delete that repo".into(), + emit, + ), + ) + .await + .expect("a stopped turn must return") + .unwrap(); + assert!(summary.stopped); + assert_eq!(summary.steps, 1); + assert_eq!(fx.runtime.approvals().pending_count(), 0); + + // The prompt was never accepted, so the engine never ran the statement. + let audit = read_audit(&fx.connection.audit_dir().unwrap(), 50); + assert!( + !audit.iter().any(|r| r.decision == "needs_approval_accepted" + || r.decision == "allow" && r.tool == "run_mutation_query"), + "{audit:?}" + ); + + // The conversation is still usable, and still well formed: the stopped + // call has a result, so a provider would accept the history. + let (emit, _events) = collector(); + let summary = fx + .runtime + .send( + model.clone(), + SafetyMode::Safe, + "are you there?".into(), + emit, + ) + .await + .unwrap(); + assert_eq!(summary.steps, 1); + let history = &model.seen()[1].messages; + let stopped_results = history + .iter() + .filter_map(|m| match m { + Message::ToolResults { results } => Some(results), + _ => None, + }) + .flatten() + .collect::>(); + assert_eq!(stopped_results.len(), 1); + assert_eq!(stopped_results[0].call_id, "c1"); + assert!(stopped_results[0].is_error); + assert!(matches!(history.last(), Some(Message::User { text }) if text == "are you there?")); + + teardown(fx).await; +} + +#[tokio::test] +async fn a_failed_model_call_leaves_no_half_turn_behind() { + if !engine_available() { + return; + } + let fx = fixture("modelerror").await; + // An empty script: the first call fails. + let failing = Scripted::new(vec![]); + let (emit, _events) = collector(); + let err = fx + .runtime + .send(failing, SafetyMode::Safe, "hello".into(), emit) + .await + .unwrap_err(); + assert!(err.to_string().contains("could not be read"), "{err}"); + + // The failed message is not in the history of the next turn. + let model = Scripted::new(vec![says("Hi.")]); + let (emit, _events) = collector(); + fx.runtime + .send(model.clone(), SafetyMode::Safe, "hello again".into(), emit) + .await + .unwrap(); + assert!(matches!( + &model.seen()[0].messages[..], + [Message::User { text }] if text == "hello again" + )); + + teardown(fx).await; +} + +#[tokio::test] +async fn changing_the_safety_mode_opens_a_new_engine_session() { + if !engine_available() { + return; + } + let fx = fixture("modes").await; + let model = Scripted::new(vec![says("one"), says("two"), says("three")]); + + let mut sessions = Vec::new(); + for mode in [SafetyMode::Safe, SafetyMode::Safe, SafetyMode::ReadOnly] { + let (emit, events) = collector(); + fx.runtime + .send(model.clone(), mode, "hi".into(), emit) + .await + .unwrap(); + let started = events + .lock() + .unwrap() + .iter() + .filter(|e| matches!(e, AgentEvent::SessionStarted { .. })) + .count(); + sessions.push(started); + } + // Opened once, reused while the mode stayed the same, reopened on change. + assert_eq!(sessions, vec![1, 0, 1]); + // The conversation carried across all three turns. + assert_eq!(model.seen()[2].messages.len(), 5); + + teardown(fx).await; +} + +#[tokio::test] +async fn without_a_running_engine_the_turn_fails_plainly() { + let approot = std::env::temp_dir().join(format!("wb-agent-it-{}-noengine", std::process::id())); + let settings = Arc::new(SettingsStore::in_memory(Settings::default())); + let connection = Arc::new( + LocalConnection::new( + ApprootDefaults::fixed(approot.clone()), + approot.join("audit"), + settings, + ) + .unwrap(), + ); + let runtime = AgentRuntime::new(connection); + let (emit, _events) = collector(); + let err = runtime + .send( + Scripted::new(vec![says("x")]), + SafetyMode::Safe, + "hi".into(), + emit, + ) + .await + .unwrap_err(); + assert!(err.to_string().contains("engine is not running"), "{err}"); +} diff --git a/src-tauri/tests/engine_integration.rs b/src-tauri/tests/engine_integration.rs new file mode 100644 index 0000000..e53d77b --- /dev/null +++ b/src-tauri/tests/engine_integration.rs @@ -0,0 +1,574 @@ +//! Integration tests against a real `stackql` binary. +//! +//! They are skipped, with a note on stderr, when no binary can be found. They +//! need no cloud credentials and no network: every statement is a metadata +//! statement or a literal `SELECT`, and the only provider used is the one +//! built into the engine. + +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use stackql_workbench_lib::config::{Settings, SettingsStore}; +use stackql_workbench_lib::connection::local::LocalConnection; +use stackql_workbench_lib::connection::{ + Connection, DelegateCommand, EngineState, EventSink, McpServerCommand, SafetyMode, +}; +use stackql_workbench_lib::engine::approot::Defaults as ApprootDefaults; +use stackql_workbench_lib::engine::discovery::{self, Inputs}; +use stackql_workbench_lib::error::HostError; +use stackql_workbench_lib::query::explorer; +use stackql_workbench_lib::query::result::QueryEvent; + +/// The provider compiled into the engine. It is there on a fresh approot. +const BUILT_IN_PROVIDER: &str = "stackql_preview"; + +fn engine_available() -> bool { + let found = discovery::resolve(&Inputs::from_environment(None), |p| p.is_file()).is_ok(); + if !found { + eprintln!("skipped: no stackql binary found (set STACKQL_BIN or add stackql to PATH)"); + } + found +} + +fn scratch_approot(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("wb-it-{}-{name}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + dir +} + +async fn started(name: &str) -> (LocalConnection, PathBuf) { + let approot = scratch_approot(name); + let settings = Arc::new(SettingsStore::in_memory(Settings::default())); + let connection = LocalConnection::new( + ApprootDefaults::fixed(approot.clone()), + approot.join("audit"), + settings, + ) + .unwrap(); + let status = connection.start().await; + assert_eq!( + status.state, + EngineState::Running, + "engine did not start: {:?} {:?}", + status.error, + status.log_tail + ); + (connection, approot) +} + +async fn finish(connection: LocalConnection, approot: PathBuf) { + connection.shutdown().await; + assert_eq!(connection.status().state, EngineState::Stopped); + let _ = std::fs::remove_dir_all(approot); +} + +fn collector() -> (EventSink, Arc>>) { + let events: Arc>> = Arc::default(); + let sink_events = events.clone(); + let sink: EventSink = Box::new(move |event| sink_events.lock().unwrap().push(event)); + (sink, events) +} + +#[tokio::test] +async fn starts_reports_status_and_stops() { + if !engine_available() { + return; + } + let (connection, approot) = started("status").await; + + let status = connection.status(); + assert!( + status + .location + .as_deref() + .is_some_and(|l| l.contains("stackql")) + ); + assert!(status.location_source.is_some()); + let version = status.version.clone().unwrap(); + assert!( + version.chars().next().is_some_and(|c| c.is_ascii_digit()), + "unexpected version {version:?}" + ); + let endpoint = status.endpoint.clone().unwrap(); + assert!( + endpoint.starts_with("127.0.0.1:"), + "must be loopback: {endpoint}" + ); + assert_eq!(status.error, None); + + finish(connection, approot).await; +} + +#[tokio::test] +async fn runs_a_metadata_statement_and_streams_rows() { + if !engine_available() { + return; + } + let (connection, approot) = started("metadata").await; + + let (sink, events) = collector(); + let summary = connection + .run("run-1".into(), "SHOW PROVIDERS".into(), sink) + .await + .unwrap(); + assert_eq!(summary.statements, 1); + assert_eq!(summary.completed, 1); + assert!(!summary.failed && !summary.abandoned); + + let events = events.lock().unwrap().clone(); + assert!(matches!( + &events[0], + QueryEvent::StatementStarted { index: 0, total: 1, sql } if sql == "SHOW PROVIDERS" + )); + let columns = events.iter().find_map(|e| match e { + QueryEvent::Columns { columns, .. } => Some(columns.clone()), + _ => None, + }); + assert_eq!( + columns, + Some(vec!["name".to_string(), "version".to_string()]) + ); + let rows: Vec<_> = events + .iter() + .filter_map(|e| match e { + QueryEvent::Rows { rows, .. } => Some(rows.clone()), + _ => None, + }) + .flatten() + .collect(); + assert!( + rows.iter() + .any(|r| r[0].as_deref() == Some(BUILT_IN_PROVIDER)), + "built-in provider missing from {rows:?}" + ); + let finished = events.iter().find_map(|e| match e { + QueryEvent::StatementFinished { row_count, .. } => Some(*row_count), + _ => None, + }); + // The engine's command tag has no count. The host counts. + assert_eq!(finished, Some(rows.len() as u64)); + + finish(connection, approot).await; +} + +#[tokio::test] +async fn every_statement_in_the_text_runs_not_just_the_first() { + if !engine_available() { + return; + } + let (connection, approot) = started("multi").await; + + // Sent as one message, the engine would run only the first of these. + let (sink, events) = collector(); + let summary = connection + .run( + "run-1".into(), + "SHOW VERSION; SELECT 1 AS one, 'a,b' AS s; -- done".into(), + sink, + ) + .await + .unwrap(); + let events = events.lock().unwrap().clone(); + assert_eq!(summary.statements, 2); + assert_eq!(summary.completed, 2, "{events:?}"); + + let second_rows: Vec<_> = events + .iter() + .filter_map(|e| match e { + QueryEvent::Rows { index: 1, rows } => Some(rows.clone()), + _ => None, + }) + .flatten() + .collect(); + assert_eq!( + second_rows, + vec![vec![Some("1".to_string()), Some("a,b".to_string())]], + "values are text" + ); + + finish(connection, approot).await; +} + +#[tokio::test] +async fn an_error_stops_the_run_and_the_session_stays_usable() { + if !engine_available() { + return; + } + let (connection, approot) = started("errors").await; + + let (sink, events) = collector(); + let summary = connection + .run( + "run-1".into(), + "SHOW VERSION; SELEC 1; SHOW PROVIDERS".into(), + sink, + ) + .await + .unwrap(); + assert_eq!(summary.statements, 3); + assert_eq!(summary.completed, 1); + assert!(summary.failed); + + let events = events.lock().unwrap().clone(); + let error = events + .iter() + .find_map(|e| match e { + QueryEvent::StatementFailed { + index: 1, error, .. + } => Some(error.clone()), + _ => None, + }) + .expect("the second statement should fail"); + assert_eq!(error.severity.as_deref(), Some("ERROR")); + assert_eq!(error.code.as_deref(), Some("XXUUU")); + assert!(error.message.contains("syntax"), "{}", error.message); + assert!(!error.connection_lost); + assert!( + !events + .iter() + .any(|e| matches!(e, QueryEvent::StatementStarted { index: 2, .. })), + "nothing runs after a failure" + ); + + // The same session takes the next run. + let (sink, _) = collector(); + let summary = connection + .run("run-2".into(), "SHOW VERSION".into(), sink) + .await + .unwrap(); + assert_eq!(summary.completed, 1); + + finish(connection, approot).await; +} + +#[tokio::test] +async fn explorer_statements_work_against_the_built_in_provider() { + if !engine_available() { + return; + } + let (connection, approot) = started("explorer").await; + + let providers = explorer::map_providers( + &connection + .fetch(explorer::PROVIDERS_SQL.to_string()) + .await + .unwrap(), + ) + .unwrap(); + assert!(providers.iter().any(|p| p.name == BUILT_IN_PROVIDER)); + + let services = explorer::map_services( + &connection + .fetch(explorer::services_sql(BUILT_IN_PROVIDER).unwrap()) + .await + .unwrap(), + ) + .unwrap(); + assert!(!services.is_empty(), "the built-in provider has services"); + let service = &services[0].name; + + let resources = explorer::map_resources( + &connection + .fetch(explorer::resources_sql(BUILT_IN_PROVIDER, service).unwrap()) + .await + .unwrap(), + ) + .unwrap(); + assert!(!resources.is_empty(), "service {service} has resources"); + let resource = &resources[0]; + assert_eq!( + resource.id, + format!("{BUILT_IN_PROVIDER}.{service}.{}", resource.name), + "the resource id is the fully qualified name" + ); + + // An unknown name is an engine error, carried back as a query error. + let err = connection + .fetch(explorer::services_sql("no_such_provider_xyz").unwrap()) + .await + .unwrap_err(); + assert!(matches!(err, HostError::Query(_))); + + finish(connection, approot).await; +} + +#[tokio::test] +async fn a_run_without_an_engine_says_so() { + let approot = scratch_approot("stopped"); + let settings = Arc::new(SettingsStore::in_memory(Settings::default())); + let connection = LocalConnection::new( + ApprootDefaults::fixed(approot.clone()), + approot.join("audit"), + settings, + ) + .unwrap(); + let (sink, _) = collector(); + let err = connection + .run("run-1".into(), "SHOW VERSION".into(), sink) + .await + .unwrap_err(); + assert_eq!(err, HostError::EngineNotRunning); + assert!(!connection.abandon("run-1")); +} + +#[tokio::test] +async fn a_wrong_engine_path_is_reported_in_the_status() { + let approot = scratch_approot("badpath"); + let settings = Arc::new(SettingsStore::in_memory(Settings { + engine_path: Some("/definitely/not/here/stackql".into()), + ..Settings::default() + })); + let connection = LocalConnection::new( + ApprootDefaults::fixed(approot.clone()), + approot.join("audit"), + settings, + ) + .unwrap(); + let status = connection.start().await; + assert_eq!(status.state, EngineState::Failed); + let error = status.error.unwrap(); + assert!(error.contains("Settings"), "points at settings: {error}"); +} + +#[tokio::test] +async fn the_data_folder_defaults_to_beside_the_app_and_settings_override_it() { + if !engine_available() { + return; + } + let root = scratch_approot("datafolder"); + let beside = root.join("app").join(".stackql"); + let fallback = root.join("data").join("engine"); + let named = root.join("named"); + + // With nothing in settings, the folder beside the app is used. + let settings = Arc::new(SettingsStore::in_memory(Settings::default())); + let connection = LocalConnection::new( + ApprootDefaults { + beside_app: Some(beside.clone()), + fallback: fallback.clone(), + }, + root.join("audit"), + settings.clone(), + ) + .unwrap(); + let status = connection.start().await; + assert_eq!(status.state, EngineState::Running, "{:?}", status.error); + assert_eq!( + status.data_folder.as_deref(), + Some(beside.to_str().unwrap()) + ); + assert_eq!(status.data_folder_source.as_deref(), Some("beside the app")); + assert_eq!(status.data_folder_note, None); + assert!(beside.is_dir(), "the engine's folder exists"); + assert!(!fallback.exists(), "the fallback is left alone"); + + // A folder named in settings takes over at the next start. + settings + .replace(Settings { + approot: Some(named.to_str().unwrap().to_string()), + ..Settings::default() + }) + .unwrap(); + let status = connection.restart().await; + assert_eq!(status.state, EngineState::Running, "{:?}", status.error); + assert_eq!(status.data_folder.as_deref(), Some(named.to_str().unwrap())); + assert_eq!(status.data_folder_source.as_deref(), Some("settings")); + let (sink, _) = collector(); + let summary = connection + .run("run-1".into(), "SHOW PROVIDERS".into(), sink) + .await + .unwrap(); + assert_eq!(summary.completed, 1); + assert!(named.is_dir()); + + finish(connection, root).await; +} + +#[tokio::test] +async fn a_data_folder_that_cannot_be_used_is_reported_in_the_status() { + if !engine_available() { + return; + } + let root = scratch_approot("baddatafolder"); + std::fs::create_dir_all(&root).unwrap(); + // A file where the folder should be. + let blocked = root.join("not-a-folder"); + std::fs::write(&blocked, b"x").unwrap(); + + let settings = Arc::new(SettingsStore::in_memory(Settings { + approot: Some(blocked.to_str().unwrap().to_string()), + ..Settings::default() + })); + let connection = LocalConnection::new( + ApprootDefaults::fixed(root.join("engine")), + root.join("audit"), + settings, + ) + .unwrap(); + let status = connection.start().await; + assert_eq!(status.state, EngineState::Failed); + let error = status.error.unwrap(); + assert!(error.contains("Settings"), "points at settings: {error}"); + assert!( + !root.join("engine").exists(), + "a folder named in settings is never replaced by a default" + ); + let _ = std::fs::remove_dir_all(root); +} + +#[tokio::test] +async fn a_delegate_is_told_how_the_mcp_server_starts_and_gets_piped_stdio() { + if !engine_available() { + return; + } + let (connection, approot) = started("delegate").await; + let binary = PathBuf::from(connection.status().location.unwrap()); + + let seen: Arc>> = Arc::default(); + let sink = seen.clone(); + // Any program that writes to stdout stands in for an agent here. + let program = binary.clone(); + let cwd = approot.clone(); + let mut channel = connection + .open_delegate_channel( + SafetyMode::ReadOnly, + Box::new(move |server| { + *sink.lock().unwrap() = Some(server); + Ok(DelegateCommand { + program, + args: vec!["--version".into()], + cwd, + }) + }), + ) + .await + .unwrap(); + + // The builder was told to start the same binary, on the same data + // folder, over stdio, in the mode that was asked for. + let server = seen.lock().unwrap().clone().unwrap(); + assert_eq!(server.program, binary); + assert_eq!(server.cwd, approot); + let args: Vec = server + .args + .iter() + .map(|arg| arg.to_string_lossy().into_owned()) + .collect(); + let after = |flag: &str| args[args.iter().position(|a| a == flag).unwrap() + 1].clone(); + assert_eq!(args[0], "mcp"); + assert!(args.contains(&"--mcp.server.type=stdio".to_string())); + assert_eq!(after("--approot"), approot.to_string_lossy()); + let config: serde_json::Value = serde_json::from_str(&after("--mcp.config")).unwrap(); + assert_eq!(config["server"]["mode"], "read_only"); + assert_eq!(config["server"]["transport"], "stdio"); + + // What the program writes arrives on the channel. + let mut text = String::new(); + tokio::time::timeout( + Duration::from_secs(10), + tokio::io::AsyncReadExt::read_to_string(&mut channel.reader, &mut text), + ) + .await + .expect("the program did not finish") + .unwrap(); + assert!(text.starts_with("stackql"), "unexpected output {text:?}"); + + drop(channel); + finish(connection, approot).await; +} + +#[tokio::test] +async fn a_delegate_cannot_start_without_an_engine() { + let approot = scratch_approot("nodelegate"); + let settings = Arc::new(SettingsStore::in_memory(Settings::default())); + let connection = LocalConnection::new( + ApprootDefaults::fixed(approot.clone()), + approot.join("audit"), + settings, + ) + .unwrap(); + let asked = Arc::new(Mutex::new(false)); + let flag = asked.clone(); + let outcome = connection + .open_delegate_channel( + SafetyMode::Safe, + Box::new(move |_| { + *flag.lock().unwrap() = true; + Err(HostError::Agent("not reached".into())) + }), + ) + .await; + assert!(matches!(outcome, Err(HostError::EngineNotRunning))); + assert!(!*asked.lock().unwrap(), "nothing may be started"); +} + +#[tokio::test] +async fn restart_gives_a_working_engine_on_a_new_port() { + if !engine_available() { + return; + } + let (connection, approot) = started("restart").await; + let first = connection.status().endpoint.unwrap(); + + let status = connection.restart().await; + assert_eq!(status.state, EngineState::Running); + let second = status.endpoint.unwrap(); + assert!(second.starts_with("127.0.0.1:")); + // Not guaranteed to differ, but the old engine must be gone either way. + let _ = first; + + let (sink, _) = collector(); + let summary = connection + .run("run-1".into(), "SHOW VERSION".into(), sink) + .await + .unwrap(); + assert_eq!(summary.completed, 1); + + finish(connection, approot).await; +} + +#[tokio::test] +async fn abandoning_a_run_returns_promptly_and_the_next_run_works() { + if !engine_available() { + return; + } + let (connection, approot) = started("abandon").await; + let connection = Arc::new(connection); + + // REGISTRY LIST calls the registry and takes around a second when the + // network is up. If it is down the statement fails fast, and the test + // still checks that the session recovers. + let runner = connection.clone(); + let (sink, _) = collector(); + let run = tokio::spawn(async move { + runner + .run( + "slow".into(), + "REGISTRY LIST; REGISTRY LIST; REGISTRY LIST".into(), + sink, + ) + .await + }); + tokio::time::sleep(Duration::from_millis(150)).await; + let was_running = connection.abandon("slow"); + let summary = tokio::time::timeout(Duration::from_secs(20), run) + .await + .expect("an abandoned run must return") + .unwrap() + .unwrap(); + if was_running && !summary.failed { + assert!(summary.abandoned, "{summary:?}"); + assert!(summary.completed < 3); + } + + let (sink, _) = collector(); + let summary = connection + .run("after".into(), "SHOW VERSION".into(), sink) + .await + .unwrap(); + assert_eq!(summary.completed, 1, "a fresh session takes over"); + + let connection = Arc::try_unwrap(connection).ok().expect("no other owners"); + finish(connection, approot).await; +} diff --git a/src/App.tsx b/src/App.tsx new file mode 100644 index 0000000..9ea4494 --- /dev/null +++ b/src/App.tsx @@ -0,0 +1,663 @@ +import { useCallback, useEffect, useMemo, useRef, useState } from 'react'; +import { host } from './host'; +import { copyText } from './host/clipboard'; +import { chatTitle, type ToolItem } from './lib/chat'; +import { execCommand } from './lib/cli'; +import { EMPTY_CATALOG, sampleStatement, type Catalog } from './lib/completion'; +import { chatSuggestions } from './lib/library'; +import { commandForKey, type CommandId } from './lib/menu'; +import { agentRun, type RunState } from './lib/results'; +import { ActivityPane } from './panes/activity/ActivityPane'; +import { ChatPane } from './panes/chat/ChatPane'; +import { Editor } from './panes/editor/Editor'; +import { HistoryList } from './panes/editor/HistoryList'; +import { TabStrip } from './panes/editor/TabStrip'; +import { Explorer, type ExplorerHandle } from './panes/explorer/Explorer'; +import { LibraryPane } from './panes/library/LibraryPane'; +import { Results } from './panes/results/Results'; +import { ChatSettings } from './panes/settings/ChatSettings'; +import { SettingsDialog } from './panes/settings/SettingsDialog'; +import { AboutDialog } from './panes/shell/AboutDialog'; +import { MenuBar } from './panes/shell/MenuBar'; +import { SideNav, type View } from './panes/shell/SideNav'; +import { EngineBanner } from './panes/statusbar/EngineBanner'; +import { StatusBar } from './panes/statusbar/StatusBar'; +import { useAgent, type AgentResult } from './state/useAgent'; +import { useEngineStatus } from './state/useEngineStatus'; +import { useLibrary } from './state/useLibrary'; +import { useQueryRun } from './state/useQueryRun'; +import { useTabs } from './state/useTabs'; +import { useTheme } from './state/useTheme'; +import { IconButton, ICON_BUTTON_CLASS } from './ui/IconButton'; +import { Check, History, Play, Terminal, Warning } from './ui/icons'; +import { Popover } from './ui/Popover'; +import { Splitter } from './ui/Splitter'; + +const WELCOME_TEXT = `-- Ctrl+Enter (Cmd+Enter on macOS) runs the selection, or everything when nothing is selected. + +SHOW PROVIDERS; + +-- See what the registry offers, then install a provider: +-- REGISTRY LIST; +-- REGISTRY PULL github; +`; + +const IS_MAC = /Mac/i.test(navigator.userAgent); +const RUN_SHORTCUT = IS_MAC ? 'Cmd+Enter' : 'Ctrl+Enter'; +const JUMP_SHORTCUT = IS_MAC ? 'Cmd+P' : 'Ctrl+P'; +const EXPLORER_WIDTH_KEY = 'workbench.explorer.width'; +const EXPLORER_WIDTH = { min: 160, max: 640, initial: 300 }; + +const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value)); + +function savedExplorerWidth(): number { + try { + const saved = Number(window.localStorage.getItem(EXPLORER_WIDTH_KEY)); + return Number.isFinite(saved) && saved > 0 + ? clamp(saved, EXPLORER_WIDTH.min, EXPLORER_WIDTH.max) + : EXPLORER_WIDTH.initial; + } catch { + return EXPLORER_WIDTH.initial; + } +} + +/** Editing commands the webview carries out on whatever has the cursor. */ +function editInPlace(action: 'undo' | 'redo' | 'cut' | 'copy' | 'selectAll') { + // There is no replacement for this call that acts on the focused field. + // eslint-disable-next-line @typescript-eslint/no-deprecated + document.execCommand(action); +} + +function resultRun(result: { + callId: string; + tool: string; + sql: string | null; + table: AgentResult['table']; + engineNotes: string[]; + elapsedMs: number; +}): RunState { + return agentRun( + `agent-${result.callId}`, + result.sql ?? result.tool, + result.table.columns, + result.table.rows, + result.elapsedMs, + result.engineNotes, + ); +} + +export function App() { + const status = useEngineStatus(); + const query = useQueryRun(); + const tabs = useTabs(WELCOME_TEXT); + const { choice: themeChoice, setChoice: setThemeChoice } = useTheme(); + const library = useLibrary(); + + // Chat is where the app opens. The explorer and activity are a click away. + const [view, setView] = useState('chat'); + const [navCollapsed, setNavCollapsed] = useState(false); + const [explorerWidth, setExplorerWidth] = useState(savedExplorerWidth); + const explorer = useRef(null); + const [editorHeight, setEditorHeight] = useState(240); + // Which part of settings is open, if any. + const [settings, setSettings] = useState<'engine' | 'model' | null>(null); + const [restarting, setRestarting] = useState(false); + const [explorerToken, setExplorerToken] = useState(0); + // A result the assistant produced, shown in the grid until the operator runs something. + const [agentResult, setAgentResult] = useState(null); + const [runsEnded, setRunsEnded] = useState(0); + // What the explorer has loaded. The editor completes names from it. + const catalog = useRef(EMPTY_CATALOG); + const [providers, setProviders] = useState([]); + const [cliCopy, setCliCopy] = useState<'idle' | 'copied' | 'failed'>('idle'); + const [aboutOpen, setAboutOpen] = useState(false); + + const showAgentResult = useCallback((result: AgentResult) => { + // Results with no columns have nothing to put in a grid. + if (result.table.columns.length > 0) { + setAgentResult(resultRun(result)); + } + // Installing a provider changes what the explorer should show. + if (result.tool === 'pull_provider') { + setExplorerToken((token) => token + 1); + } + }, []); + const agent = useAgent(showAgentResult); + + const engineRunning = status.state === 'running'; + const engineBusy = restarting || status.state === 'starting'; + const running = query.state.running; + const { run: runQuery, stopWaiting } = query; + const { config: agentConfig, send: agentSend, reset: agentReset } = agent; + const modelReady = agentConfig?.inference != null; + + const run = useCallback( + (sql: string) => { + if (running || sql.trim() === '') { + return; + } + setAgentResult(null); + void runQuery(sql).then((summary) => { + setRunsEnded((count) => count + 1); + // Installing a provider changes what the explorer should show. + if (summary && summary.completed > 0 && /\bregistry\s+pull\b/i.test(sql)) { + setExplorerToken((token) => token + 1); + } + }); + }, + [running, runQuery], + ); + + useEffect(() => { + try { + window.localStorage.setItem(EXPLORER_WIDTH_KEY, String(explorerWidth)); + } catch { + // The width is a convenience. + } + }, [explorerWidth]); + + const restart = useCallback(() => { + setRestarting(true); + void host + .engineRestart() + .catch(() => undefined) + .finally(() => { + setRestarting(false); + }); + }, []); + + const { open: openTab, active: activeEditor } = tabs; + + // A statement from the assistant, the activity list or the explorer opens + // in a tab of its own. Nothing runs until the operator runs it. + const openInEditor = useCallback( + (sql: string) => { + const statement = sql.trim(); + setView('explorer'); + openTab(`${statement}${statement.endsWith(';') ? '' : ';'}\n`); + }, + [openTab], + ); + + const getCatalog = useCallback(() => catalog.current, []); + const keepCatalog = useCallback((next: Catalog) => { + catalog.current = next; + setProviders((current) => + current.length === next.providers.length && + current.every((name, index) => name === next.providers[index]) + ? current + : next.providers, + ); + }, []); + const sample = useMemo(() => sampleStatement(providers), [providers]); + // One question about metadata, and the rest from library entries that can run here. + const suggestions = useMemo( + () => chatSuggestions(library.index?.entries ?? [], new Set(providers)), + [library.index, providers], + ); + + // A stackql exec command for what Run would run, for the operator's shell. + const copyAsCli = useCallback(() => { + const sql = activeEditor()?.runText() ?? ''; + const binary = status.location; + if (sql.trim() === '' || binary === null) { + return; + } + void host + .settingsGet() + .then( + (view) => view.settings.envFile, + () => null, + ) + .then((envFile) => + copyText( + execCommand(IS_MAC ? 'posix' : 'powershell', { + binary, + approot: status.dataFolder, + envFile, + sql, + }), + ), + ) + .then((ok) => { + setCliCopy(ok ? 'copied' : 'failed'); + window.setTimeout( + () => { + setCliCopy('idle'); + }, + ok ? 1200 : 4000, + ); + }); + }, [activeEditor, status.location, status.dataFolder]); + + const showTable = useCallback((item: ToolItem) => { + if (item.table) { + setAgentResult( + resultRun({ + callId: item.callId, + tool: item.tool, + sql: item.sql, + table: item.table, + engineNotes: item.engineNotes, + elapsedMs: item.elapsedMs ?? 0, + }), + ); + setView('explorer'); + } + }, []); + + // A message cannot go anywhere without a model. Open the place to set + // one up, and keep what was typed. + const sendChat = useCallback( + (text: string) => { + if (!modelReady) { + setSettings('model'); + return false; + } + agentSend(text); + return true; + }, + [modelReady, agentSend], + ); + + const newChat = useCallback(() => { + agentReset(); + setView('chat'); + }, [agentReset]); + + const runCommand = useCallback( + (id: CommandId) => { + switch (id) { + case 'newChat': + newChat(); + break; + case 'newTab': + setView('explorer'); + openTab(); + break; + case 'showChat': + setView('chat'); + break; + case 'showExplorer': + setView('explorer'); + break; + case 'showActivity': + setView('activity'); + break; + case 'showLibrary': + setView('library'); + break; + case 'toggleSidebar': + setNavCollapsed((collapsed) => !collapsed); + break; + case 'openSettings': + setSettings('engine'); + break; + case 'openModelSettings': + setSettings('model'); + break; + case 'restartEngine': + restart(); + break; + case 'refreshExplorer': + setExplorerToken((token) => token + 1); + setView('explorer'); + break; + case 'goToResource': + setView('explorer'); + explorer.current?.jump(); + break; + case 'themeSystem': + setThemeChoice('system'); + break; + case 'themeLight': + setThemeChoice('light'); + break; + case 'themeDark': + setThemeChoice('dark'); + break; + case 'run': + setView('explorer'); + run(activeEditor()?.runText() ?? ''); + break; + case 'runSelection': + setView('explorer'); + run(activeEditor()?.selectionOrStatement() ?? ''); + break; + case 'addProvider': + setView('explorer'); + explorer.current?.addProvider(); + break; + case 'checkUpdates': + setView('explorer'); + explorer.current?.checkUpdates(); + break; + case 'reloadCredentials': + // On this channel the engine reads credentials when it starts. + restart(); + break; + case 'openDocs': + void host.openLink('docs').catch(() => undefined); + break; + case 'openQueryLibrary': + void host.openLink('queryLibrary').catch(() => undefined); + break; + case 'reportIssue': + void host.openLink('issues').catch(() => undefined); + break; + case 'showLog': + void host.revealLog().catch(() => undefined); + break; + case 'about': + setAboutOpen(true); + break; + case 'exit': + void host.closeWindow().catch(() => undefined); + break; + case 'undo': + case 'redo': + // The editor keeps its own history, which the webview's does not see. + if (activeEditor()?.hasFocus()) { + activeEditor()?.[id](); + } else { + editInPlace(id); + } + break; + case 'cut': + case 'copy': + case 'selectAll': + editInPlace(id); + break; + } + }, + [newChat, restart, openTab, activeEditor, run, setThemeChoice], + ); + + useEffect(() => { + const onKey = (event: KeyboardEvent) => { + const id = commandForKey(event, IS_MAC); + if (id !== null) { + event.preventDefault(); + runCommand(id); + } + }; + window.addEventListener('keydown', onKey); + return () => { + window.removeEventListener('keydown', onKey); + }; + }, [runCommand]); + + const disabledCommands = useMemo( + () => + new Set([ + ...(engineBusy ? (['restartEngine', 'reloadCredentials'] as const) : []), + ...(engineRunning ? [] : (['addProvider', 'checkUpdates'] as const)), + ...(engineRunning && !running ? [] : (['run', 'runSelection'] as const)), + ]), + [engineBusy, engineRunning, running], + ); + + const chosenCommands = useMemo( + () => + new Set([ + themeChoice === 'light' + ? 'themeLight' + : themeChoice === 'dark' + ? 'themeDark' + : 'themeSystem', + ]), + [themeChoice], + ); + + return ( +
+ + { + setSettings('engine'); + }} + /> + +
+ { + setNavCollapsed((collapsed) => !collapsed); + }} + onNewChat={newChat} + onView={setView} + onSettings={() => { + setSettings('engine'); + }} + /> + + {/* Every view stays mounted, so the editor keeps its text and its + history and a running turn keeps its place while another view + is on screen. */} +
+
+ { + setSettings('model'); + }} + suggestions={suggestions} + /> +
+ +
+
+ activeEditor()?.insert(text)} + onOpenStatement={openTab} + onRunStatement={(sql, inTab) => { + if (inTab) { + openTab(`${sql}\n`); + } + run(sql); + }} + onCatalog={keepCatalog} + /> +
+ { + setExplorerWidth((width) => + clamp(width + delta, EXPLORER_WIDTH.min, EXPLORER_WIDTH.max), + ); + }} + /> + +
+
+ + { + openTab(); + }} + /> + {!engineRunning && ( + + Statements can run once the engine is up. + + )} + + } + triggerClassName={ICON_BUTTON_CLASS} + > + {(close) => ( + { + close(); + openInEditor(sql); + }} + onRun={(sql) => { + close(); + openInEditor(sql); + run(sql); + }} + /> + )} + + + {cliCopy === 'copied' ? ( + + ) : cliCopy === 'failed' ? ( + + ) : ( + + )} + + +
+ + {/* One editor per tab, all mounted, so each keeps its own + history and cursor while another is in front. */} +
+ {tabs.tabs.map((tab) => ( +
+ { + tabs.register(tab.id, handle); + }} + initialText={tabs.initialText(tab.id)} + catalog={getCatalog} + sample={sample} + onRun={run} + onChange={(text) => { + tabs.changed(tab.id, text); + }} + /> +
+ ))} +
+ { + setEditorHeight((height) => clamp(height + delta, 80, 1200)); + }} + /> +
+ +
+
+
+ +
+ { + setView('explorer'); + openTab(sql); + }} + onAddProvider={() => { + setView('explorer'); + explorer.current?.addProvider(); + }} + /> +
+ +
+ +
+
+
+ + + + {aboutOpen && ( + { + setAboutOpen(false); + }} + /> + )} + + {settings !== null && ( + { + setSettings(null); + }} + > + {agentConfig && ( + { + agent.setConfig(next); + // Opened to set a model up, and now there is one: back to + // the conversation, where the message is still waiting. + if (settings === 'model' && next.inference) { + setSettings(null); + } + }} + /> + )} + + )} +
+ ); +} diff --git a/src/host/clipboard.ts b/src/host/clipboard.ts new file mode 100644 index 0000000..0bd4573 --- /dev/null +++ b/src/host/clipboard.ts @@ -0,0 +1,15 @@ +// Copying text goes through the host. The webview's own clipboard API depends +// on focus and on how the platform webview treats the app's origin, so the +// host does it instead, the same way on every platform. + +import { invoke } from '@tauri-apps/api/core'; + +/** Copies text to the system clipboard. Resolves to false if it could not. */ +export async function copyText(text: string): Promise { + try { + await invoke('clipboard_write_text', { text }); + return true; + } catch { + return false; + } +} diff --git a/src/host/index.ts b/src/host/index.ts new file mode 100644 index 0000000..6816970 --- /dev/null +++ b/src/host/index.ts @@ -0,0 +1,183 @@ +// The only module in the webview that touches Tauri. Panes call these typed +// wrappers. An ESLint rule keeps Tauri imports out of everything else. + +import { getVersion } from '@tauri-apps/api/app'; +import { Channel, invoke } from '@tauri-apps/api/core'; +import { listen } from '@tauri-apps/api/event'; +import { getCurrentWindow } from '@tauri-apps/api/window'; +import type { + Activity, + AgentConfig, + AgentEvent, + AppLink, + ApprovalDecision, + DelegateInfo, + EngineStatus, + Field, + HostError, + InferenceSettings, + LibraryDocument, + LibraryIndex, + Method, + MethodField, + Provider, + ProviderIcon, + QueryEvent, + Resource, + RunSummary, + SafetyMode, + Service, + Settings, + SettingsView, + TurnSummary, +} from './types'; + +export type * from './types'; + +const ENGINE_STATUS_EVENT = 'engine-status'; + +/** Turns whatever a host call rejected with into a `HostError`. */ +export function toHostError(value: unknown): HostError { + if (typeof value === 'object' && value !== null) { + const candidate = value as { kind?: unknown; message?: unknown }; + if (typeof candidate.kind === 'string' && typeof candidate.message === 'string') { + return { kind: candidate.kind, message: candidate.message }; + } + if (value instanceof Error) { + return { kind: 'internal', message: value.message }; + } + } + return { kind: 'internal', message: typeof value === 'string' ? value : 'Unknown error.' }; +} + +export const host = { + engineStatus: () => invoke('engine_status'), + + /** Stops and starts the engine. Also the only way to stop a running statement. */ + engineRestart: () => invoke('engine_restart'), + + /** Calls `handler` on every status change. Returns a function that unsubscribes. */ + async onEngineStatus(handler: (status: EngineStatus) => void): Promise<() => void> { + return listen(ENGINE_STATUS_EVENT, (event) => { + handler(event.payload); + }); + }, + + settingsGet: () => invoke('settings_get'), + + /** Saves settings. The engine restarts if a setting it depends on changed. */ + settingsSave: (settings: Settings) => invoke('settings_save', { settings }), + + /** + * Runs the statements in `sql` on the operator's session. Events arrive + * through `onEvent` while the returned promise is pending. + */ + runQuery(runId: string, sql: string, onEvent: (event: QueryEvent) => void): Promise { + const channel = new Channel(); + channel.onmessage = onEvent; + return invoke('query_run', { runId, sql, onEvent: channel }); + }, + + /** Stops waiting for a run. The engine has no cancel. */ + abandonQuery: (runId: string) => invoke('query_abandon', { runId }), + + /** + * Icons for the named providers, keyed by provider name. A provider with no + * icon is absent from the result. + */ + providerIcons: (providers: string[]) => + invoke>('provider_icons', { providers }), + + agent: { + config: () => invoke('agent_config_get'), + + /** + * Saves the chat backend. A key, when given, goes to the OS keychain. + * Leaving it out keeps the key that is already stored. + */ + saveConfig: (inference: InferenceSettings, apiKey: string | null) => + invoke('agent_config_save', { inference, apiKey }), + + /** Removes the chat backend and its stored key. */ + clearConfig: () => invoke('agent_config_clear'), + + setSafetyMode: (mode: SafetyMode) => invoke('agent_set_safety_mode', { mode }), + + /** + * Sends a message to the assistant. Events arrive through `onEvent` + * while the returned promise is pending. + */ + send(text: string, onEvent: (event: AgentEvent) => void): Promise { + const channel = new Channel(); + channel.onmessage = onEvent; + return invoke('agent_send', { text, onEvent: channel }); + }, + + /** Delivers the operator's answer to an approval prompt. */ + approve: (approvalId: string, decision: ApprovalDecision) => + invoke('agent_approve', { approvalId, decision }), + + /** Stops the running turn. A statement already started is not interrupted. */ + stop: () => invoke('agent_stop'), + + /** Starts a new conversation. */ + reset: () => invoke('agent_reset'), + + /** + * Asks a delegated agent for its version and models. This starts the + * agent and sends no prompt. `program` is where the agent is, or null + * to search PATH. + */ + delegateInfo: (program: string | null) => + invoke('agent_delegate_info', { program }), + }, + + /** Closes the window, which ends the app and stops the engine. */ + closeWindow: () => getCurrentWindow().close(), + + /** + * Asks the operator where to save `contents` and writes it there. + * Resolves to the path, or to null when the dialog was dismissed. + */ + saveTextFile: (suggestedName: string, kind: 'csv' | 'json' | 'jsonl', contents: string) => + invoke('save_text_file', { suggestedName, kind, contents }), + + library: { + /** The query library's index. `refresh` asks for a new copy. */ + index: (refresh: boolean) => invoke('library_index', { refresh }), + /** One entry's document and statement. */ + document: (id: string) => invoke('library_document', { id }), + }, + + /** Opens one of the app's own links in the operator's browser. */ + openLink: (link: AppLink) => invoke('open_link', { link }), + + /** + * Shows the app's log file for this run in the system's file manager. + * The host holds the path, and resolves to it. + */ + revealLog: () => invoke('reveal_log'), + + /** The version of this app. */ + appVersion: () => getVersion(), + + /** What was run recently, by the operator and by the agent. */ + activity: (limit?: number) => invoke('activity_list', { limit }), + + explorer: { + providers: () => invoke('explorer_providers'), + /** What the registry offers, with the version of each. Needs the network. */ + registry: () => invoke('explorer_registry'), + services: (provider: string) => invoke('explorer_services', { provider }), + resources: (provider: string, service: string) => + invoke('explorer_resources', { provider, service }), + methods: (provider: string, service: string, resource: string) => + invoke('explorer_methods', { provider, service, resource }), + fields: (provider: string, service: string, resource: string) => + invoke('explorer_fields', { provider, service, resource }), + methodFields: (provider: string, service: string, resource: string, method: string) => + invoke('explorer_method_fields', { provider, service, resource, method }), + }, +}; + +export type Host = typeof host; diff --git a/src/host/types.ts b/src/host/types.ts new file mode 100644 index 0000000..d1ecc12 --- /dev/null +++ b/src/host/types.ts @@ -0,0 +1,360 @@ +// Types that cross IPC. They mirror the serialised Rust types in +// src-tauri/src. Keep the two in step. + +export type EngineState = 'stopped' | 'starting' | 'running' | 'failed'; + +export interface EngineStatus { + state: EngineState; + /** Where the engine is. For a local engine, the path of the binary. */ + location: string | null; + /** How the location was found, for example "PATH" or "settings". */ + locationSource: string | null; + version: string | null; + /** The address statements are sent to. */ + endpoint: string | null; + /** Where the engine keeps its provider cache, when that is on this machine. */ + dataFolder: string | null; + /** How the data folder was chosen, for example "settings". */ + dataFolderSource: string | null; + /** Set when the data folder is not the expected one, with the reason. */ + dataFolderNote: string | null; + error: string | null; + /** The last lines the engine wrote to stderr. */ + logTail: string[]; +} + +/** What the agent may do without asking. The engine enforces it. */ +export type SafetyMode = 'read_only' | 'safe' | 'delete_safe' | 'full_access'; + +export type BackendKind = 'gemini' | 'anthropic' | 'openai_compatible' | 'github_copilot'; + +/** Which model the chat uses. The API key is never part of this. */ +export interface InferenceSettings { + kind: BackendKind; + /** Empty means the backend's default model. */ + model: string; + /** Null means the backend's default address. */ + baseUrl: string | null; + /** For a delegated agent: where its program is. Null searches PATH. */ + program: string | null; + /** For a delegated agent: whether it may split work across subagents. */ + subagents: boolean; +} + +export interface Settings { + /** Explicit location of the stackql binary. Null means search for it. */ + enginePath: string | null; + /** A dotenv file the engine sources at startup. The app never reads it. */ + envFile: string | null; + /** The engine's data folder, its --approot. Null means the default. */ + approot: string | null; + safetyMode: SafetyMode; + /** Null means chat is not configured. */ + inference: InferenceSettings | null; +} + +export interface SettingsView { + settings: Settings; + warning: string | null; +} + +/** One row. Values are text, or null for a protocol NULL. */ +export type Row = (string | null)[]; + +export interface Notice { + severity: string; + code: string; + message: string; + /** For this engine the useful text is here. */ + detail: string | null; +} + +export interface QueryError { + severity: string | null; + code: string | null; + message: string; + connectionLost: boolean; +} + +export type QueryEvent = + | { event: 'statementStarted'; data: { index: number; total: number; sql: string } } + | { event: 'columns'; data: { index: number; columns: string[] } } + | { event: 'rows'; data: { index: number; rows: Row[] } } + | { event: 'notice'; data: { index: number; notice: Notice } } + | { event: 'engineLog'; data: { index: number; lines: string[] } } + | { event: 'statementFinished'; data: { index: number; rowCount: number; elapsedMs: number } } + | { event: 'statementFailed'; data: { index: number; error: QueryError; elapsedMs: number } }; + +export interface RunSummary { + statements: number; + completed: number; + failed: boolean; + /** The operator stopped waiting. The statement may still complete in the engine. */ + abandoned: boolean; + elapsedMs: number; +} + +/** One entry of the query library, as its index describes it. */ +export interface LibraryEntry { + /** For example github/repos/org-repos-list. */ + id: string; + title: string; + description: string; + providers: string[]; + services: string[]; + tags: string[]; + keywords: string[]; + intentKeywords: string[]; + /** The library's own word on whether the statement changes anything. */ + mutation: boolean; + verb: string; + /** For example stable or draft. */ + status: string; + requiredParams: string[]; +} + +export interface LibraryIndex { + entries: LibraryEntry[]; + buildId: string; + /** The library could not be reached. This is the copy kept from an earlier time. */ + fromCache: boolean; +} + +export interface LibraryDocument { + id: string; + /** The entry's document, without its front matter. */ + markdown: string; + /** The entry's statement, a template with {{name}} where a value goes. */ + statement: string | null; +} + +/** One of the app's own links. The host holds the address. */ +export type AppLink = 'docs' | 'queryLibrary' | 'issues'; + +/** What a rejected host call carries. */ +export interface HostError { + kind: string; + message: string; +} + +export interface Provider { + name: string; + version: string; +} + +export interface ProviderIcon { + /** The image as a data: URL. */ + dataUrl: string; + /** The icon is dark on a transparent background and needs inverting on a dark surface. */ + invertOnDark: boolean; + /** For example "Amazon Web Services". */ + displayName: string; +} + +export interface Service { + name: string; + id: string; + title: string; + description: string; +} + +export interface Resource { + name: string; + /** The fully qualified name. */ + id: string; + description: string; +} + +export interface Method { + name: string; + sqlVerb: string; + requiredParams: string[]; + description: string; +} + +export interface Field { + name: string; + type: string; + description: string; +} + +export interface MethodField { + name: string; + type: string; + /** input_required, input_optional or output. */ + paramType: string; + shape: string; + description: string; +} + +export interface BackendOption { + kind: BackendKind; + defaultModel: string; + defaultBaseUrl: string; + /** A local server usually needs no key. */ + keyOptional: boolean; + /** + * An agent the operator installed runs the model. There is no key and no + * address to enter, and no approval prompt. + */ + delegated: boolean; +} + +/** A model a delegated agent offers. */ +export interface AgentModel { + id: string; + name: string; + description: string; + /** What a request costs against the operator's plan, for example "1x". */ + usage: string | null; +} + +/** What a delegated agent says about itself. */ +export interface DelegateInfo { + version: string; + currentModel: string | null; + models: AgentModel[]; +} + +/** What the webview may know about the chat setup. Never the key itself. */ +export interface AgentConfig { + /** Null means no model backend is set up yet. */ + inference: InferenceSettings | null; + hasKey: boolean; + safetyMode: SafetyMode; + backends: BackendOption[]; + /** False when keys cannot be kept in the OS keychain on this machine. */ + keychainAvailable: boolean; +} + +/** The engine asks the operator before it runs something. */ +export interface ApprovalRequest { + id: string; + /** The engine's message, exactly as sent. */ + message: string; + tool: string | null; + /** The engine's classification, for example mutation_delete. */ + queryClass: string | null; + /** The exact SQL. */ + sql: string | null; +} + +export type ApprovalDecision = 'accept' | 'decline' | 'cancel'; + +/** A row result from a tool, in the shape the grid uses. */ +export interface AgentTable { + columns: string[]; + rows: Row[]; + /** Rows the tool returned, which can be more than were sent on. */ + totalRows: number; + truncated: boolean; +} + +export type AgentEvent = + | { + event: 'sessionStarted'; + data: { mode: SafetyMode; protocolVersion: string; tools: number }; + } + | { + event: 'delegateStarted'; + data: { + mode: SafetyMode; + /** The agent's name, for example "GitHub Copilot CLI". */ + agent: string; + version: string; + /** The protocol it is driven over, for example "ACP 1". */ + protocol: string; + model: string | null; + tools: number; + }; + } + | { event: 'assistantText'; data: { text: string } } + /** A piece of the reply as it is written. Pieces with one id are one message. */ + | { event: 'assistantDelta'; data: { id: string; text: string } } + | { + event: 'toolCallStarted'; + data: { + id: string; + tool: string; + arguments: unknown; + sql: string | null; + /** The subagent that made the call. Absent for the main agent. */ + agent?: string; + /** Which of the model's steps in this turn asked for the call. */ + step: number; + }; + } + | { event: 'approvalRequested'; data: { request: ApprovalRequest } } + | { + event: 'toolCallFinished'; + data: { + id: string; + isError: boolean; + text: string; + table: AgentTable | null; + /** Provider API failures the engine reported while the tool ran. */ + engineNotes: string[]; + elapsedMs: number; + }; + } + | { event: 'notice'; data: { message: string } }; + +export type StopReason = + | { kind: 'endTurn' } + | { kind: 'toolUse' } + | { kind: 'maxTokens' } + | { kind: 'refused'; detail: string } + | { kind: 'other'; detail: string }; + +export interface TurnSummary { + /** Calls made to the model. */ + steps: number; + toolCalls: number; + /** The operator stopped the turn. */ + stopped: boolean; + stop: StopReason; + usage: TokenUsage; +} + +/** + * What a turn used, added up over every call to the model in it. A count is + * null when the provider did not report it, which is not the same as zero. + */ +export interface TokenUsage { + /** Everything the model was sent, what was read from a cache included. */ + inputTokens: number | null; + /** Everything the model wrote, with its thinking where the provider counts it. */ + outputTokens: number | null; + /** The part of the input the provider read from its cache. */ + cachedInputTokens: number | null; +} + +/** One statement the operator ran. */ +export interface HistoryEntry { + timestampMs: number; + sql: string; + /** ok, error or abandoned. */ + outcome: string; + rows: number | null; + elapsedMs: number; + error: string | null; +} + +/** One record from the engine's agent audit log. */ +export interface AuditRecord { + /** RFC 3339. */ + timestamp: string; + tool: string; + mode: string; + /** For example allow, refuse_immediate or needs_approval_declined. */ + decision: string; + queryClass: string; + sql: string | null; + durationMs: number | null; + error: string | null; +} + +export interface Activity { + operator: HistoryEntry[]; + agent: AuditRecord[]; +} diff --git a/src/lib/activity.test.ts b/src/lib/activity.test.ts new file mode 100644 index 0000000..b794ac4 --- /dev/null +++ b/src/lib/activity.test.ts @@ -0,0 +1,290 @@ +import { describe, expect, it } from 'vitest'; +import type { Activity } from '../host/types'; +import { + NO_FILTER, + OUTCOME_CHOICES, + activityJsonl, + activityRows, + filterActivity, + formatTime, +} from './activity'; + +const activity: Activity = { + operator: [ + { + timestampMs: Date.parse('2026-11-18T10:00:00Z'), + sql: 'SHOW PROVIDERS', + outcome: 'ok', + rows: 3, + elapsedMs: 4, + error: null, + }, + { + timestampMs: Date.parse('2026-11-18T10:02:00Z'), + sql: 'SELEC 1', + outcome: 'error', + rows: null, + elapsedMs: 1, + error: 'syntax error', + }, + { + timestampMs: Date.parse('2026-11-18T10:04:00Z'), + sql: 'SELECT slow', + outcome: 'abandoned', + rows: null, + elapsedMs: 0, + error: null, + }, + ], + agent: [ + { + timestamp: '2026-11-18T21:01:00+11:00', + tool: 'list_providers', + mode: 'safe', + decision: 'allow', + queryClass: 'select', + sql: null, + durationMs: 1, + error: null, + }, + { + timestamp: '2026-11-18T21:03:00+11:00', + tool: 'run_mutation_query', + mode: 'safe', + decision: 'needs_approval_declined', + queryClass: 'mutation_delete', + sql: 'DELETE FROM t', + durationMs: 0, + error: 'refused: user declined approval', + }, + { + timestamp: '2026-11-18T21:05:00+11:00', + tool: 'run_select_query', + mode: 'safe', + decision: 'allow', + queryClass: 'select', + sql: 'SELECT x', + durationMs: 40, + error: 'no such column', + }, + ], +}; + +describe('activityRows', () => { + const rows = activityRows(activity); + + it('merges both channels, newest first, across time zones', () => { + expect(rows.map((r) => r.label)).toEqual([ + 'SELECT x', + 'SELECT slow', + 'DELETE FROM t', + 'SELEC 1', + 'list_providers', + 'SHOW PROVIDERS', + ]); + expect(rows.map((r) => r.channel)).toEqual([ + 'agent', + 'operator', + 'agent', + 'operator', + 'agent', + 'operator', + ]); + }); + + it('describes what the operator ran', () => { + const ok = rows.find((r) => r.label === 'SHOW PROVIDERS'); + expect(ok).toMatchObject({ + outcome: 'Ran', + kind: 'ran', + tone: 'ok', + mode: '', + rowCount: 3, + durationMs: 4, + detail: '', + sql: 'SHOW PROVIDERS', + }); + const failed = rows.find((r) => r.label === 'SELEC 1'); + expect(failed).toMatchObject({ + outcome: 'Failed', + kind: 'failed', + tone: 'error', + error: 'syntax error', + }); + const abandoned = rows.find((r) => r.label === 'SELECT slow'); + // The app stopped waiting, so it has no duration to show. + expect(abandoned).toMatchObject({ + outcome: 'Stopped waiting', + kind: 'stopped', + tone: 'warn', + durationMs: null, + }); + }); + + it('describes what the agent did, using the engine decision', () => { + const declined = rows.find((r) => r.label === 'DELETE FROM t'); + expect(declined).toMatchObject({ + outcome: 'Declined', + kind: 'declined', + tone: 'warn', + mode: 'safe', + durationMs: 0, + detail: 'run_mutation_query, mutation_delete', + decision: 'needs_approval_declined', + }); + const listed = rows.find((r) => r.label === 'list_providers'); + expect(listed).toMatchObject({ + outcome: 'Ran', + kind: 'ran', + tone: 'ok', + sql: null, + detail: 'select', + tool: 'list_providers', + }); + // The audit log carries no row count, so none is shown. + expect(rows.filter((r) => r.channel === 'agent').every((r) => r.rowCount === null)).toBe(true); + }); + + it('does not call an allowed call that failed a success', () => { + const failed = rows.find((r) => r.label === 'SELECT x'); + expect(failed).toMatchObject({ outcome: 'Ran, with an error', kind: 'failed', tone: 'error' }); + }); + + it('shows an unknown decision as the engine wrote it', () => { + const [row] = activityRows({ + operator: [], + agent: [ + { + timestamp: 'not a date', + tool: 'list_providers', + mode: 'safe', + decision: 'something_new', + queryClass: 'select', + sql: null, + durationMs: 1, + error: null, + }, + ], + }); + expect(row).toMatchObject({ + outcome: 'something_new', + kind: 'other', + tone: 'muted', + time: 0, + }); + }); + + it('gives every row a distinct key', () => { + expect(new Set(rows.map((r) => r.key)).size).toBe(rows.length); + }); +}); + +describe('the engine decisions', () => { + const decided = (decision: string) => + activityRows({ + operator: [], + agent: [ + { + timestamp: '2026-11-18T10:00:00Z', + tool: 'run_mutation_query', + mode: 'read_only', + decision, + queryClass: 'mutation_delete', + sql: 'DELETE FROM t', + durationMs: 0, + error: null, + }, + ], + })[0]?.kind; + + it('are grouped for filtering as the engine wrote them', () => { + expect(decided('allow')).toBe('ran'); + expect(decided('needs_approval_accepted')).toBe('approved'); + expect(decided('needs_approval_declined')).toBe('declined'); + expect(decided('needs_approval_cancelled')).toBe('declined'); + expect(decided('needs_approval_unavailable')).toBe('refused'); + expect(decided('refuse_immediate')).toBe('refused'); + }); +}); + +describe('filterActivity', () => { + const rows = activityRows(activity); + + it('keeps everything with no filter', () => { + expect(filterActivity(rows, NO_FILTER)).toHaveLength(rows.length); + }); + + it('narrows by who ran it', () => { + expect(filterActivity(rows, { actor: 'agent', outcome: 'all' }).map((r) => r.label)).toEqual([ + 'SELECT x', + 'DELETE FROM t', + 'list_providers', + ]); + expect(filterActivity(rows, { actor: 'operator', outcome: 'all' })).toHaveLength(3); + }); + + it('narrows by what became of it, and by both at once', () => { + expect(filterActivity(rows, { actor: 'all', outcome: 'failed' }).map((r) => r.label)).toEqual([ + 'SELECT x', + 'SELEC 1', + ]); + expect( + filterActivity(rows, { actor: 'agent', outcome: 'declined' }).map((r) => r.label), + ).toEqual(['DELETE FROM t']); + expect(filterActivity(rows, { actor: 'operator', outcome: 'declined' })).toEqual([]); + }); + + it('offers each outcome the list can hold, once', () => { + const values = OUTCOME_CHOICES.map((choice) => choice.value); + expect(new Set(values).size).toBe(values.length); + expect(values).toEqual(['ran', 'failed', 'refused', 'approved', 'declined', 'stopped']); + }); +}); + +describe('activityJsonl', () => { + it('writes one object on each line', () => { + const rows = activityRows(activity); + const text = activityJsonl(rows); + const lines = text.split('\n'); + expect(lines.pop()).toBe(''); + expect(lines).toHaveLength(rows.length); + expect(JSON.parse(lines[2] ?? '')).toEqual({ + time: '2026-11-18T10:03:00.000Z', + actor: 'agent', + mode: 'safe', + statement: 'DELETE FROM t', + tool: 'run_mutation_query', + durationMs: 0, + rows: null, + outcome: 'declined', + decision: 'needs_approval_declined', + error: 'refused: user declined approval', + }); + expect(JSON.parse(lines[5] ?? '')).toEqual({ + time: '2026-11-18T10:00:00.000Z', + actor: 'operator', + mode: null, + statement: 'SHOW PROVIDERS', + tool: null, + durationMs: 4, + rows: 3, + outcome: 'ran', + decision: null, + error: null, + }); + }); + + it('writes nothing for no rows', () => { + expect(activityJsonl([])).toBe(''); + }); +}); + +describe('formatTime', () => { + it('shows only the clock for today and the date otherwise', () => { + const now = new Date(); + now.setHours(9, 5, 7, 0); + expect(formatTime(now.getTime())).toBe('09:05:07'); + expect(formatTime(new Date(2020, 0, 2, 3, 4, 5).getTime())).toBe('2020-01-02 03:04:05'); + expect(formatTime(0)).toBe(''); + }); +}); diff --git a/src/lib/activity.ts b/src/lib/activity.ts new file mode 100644 index 0000000..ff4ad34 --- /dev/null +++ b/src/lib/activity.ts @@ -0,0 +1,171 @@ +// The activity pane's rows: the operator's statement history and the +// engine's agent audit log, merged into one list by time. +// +// What happened to an agent's call is the engine's decision, read from its +// audit log. Nothing here works an outcome out from the statement. + +import type { Activity, AuditRecord, HistoryEntry } from '../host/types'; + +/** What became of a statement, in the terms the list is filtered by. */ +export type OutcomeKind = + 'ran' | 'failed' | 'refused' | 'approved' | 'declined' | 'stopped' | 'other'; + +export interface ActivityRow { + key: string; + /** Milliseconds since the Unix epoch. 0 when the time could not be read. */ + time: number; + channel: 'operator' | 'agent'; + /** The safety mode an agent's call ran under. Empty for the operator. */ + mode: string; + /** The statement, or the tool name when the call carried no statement. */ + label: string; + /** The statement, when there is one to open in the editor. */ + sql: string | null; + durationMs: number | null; + /** Rows returned. The engine's audit log has no count, so agent rows have none. */ + rowCount: number | null; + kind: OutcomeKind; + /** The outcome in words. An engine decision this app does not know is shown as written. */ + outcome: string; + tone: 'ok' | 'warn' | 'error' | 'muted'; + /** For an agent's call: the tool and the engine's classification. */ + detail: string; + /** For an agent's call: the engine tool that was called. */ + tool: string | null; + /** For an agent's call: the engine's decision as written in its log. */ + decision: string | null; + error: string | null; +} + +const DECISIONS: Record = + { + allow: { outcome: 'Ran', tone: 'ok', kind: 'ran' }, + needs_approval_accepted: { outcome: 'Approved and ran', tone: 'ok', kind: 'approved' }, + needs_approval_declined: { outcome: 'Declined', tone: 'warn', kind: 'declined' }, + needs_approval_cancelled: { outcome: 'Dismissed', tone: 'warn', kind: 'declined' }, + needs_approval_unavailable: { + outcome: 'Refused, no approval possible', + tone: 'error', + kind: 'refused', + }, + refuse_immediate: { outcome: 'Refused', tone: 'error', kind: 'refused' }, + }; + +function operatorRow(entry: HistoryEntry, index: number): ActivityRow { + const failed = entry.outcome === 'error'; + const abandoned = entry.outcome === 'abandoned'; + return { + key: `o-${entry.timestampMs}-${index}`, + time: entry.timestampMs, + channel: 'operator', + mode: '', + label: entry.sql, + sql: entry.sql, + // The app stopped waiting, so it does not know how long the engine took. + durationMs: abandoned ? null : entry.elapsedMs, + rowCount: entry.rows, + kind: failed ? 'failed' : abandoned ? 'stopped' : 'ran', + outcome: failed ? 'Failed' : abandoned ? 'Stopped waiting' : 'Ran', + tone: failed ? 'error' : abandoned ? 'warn' : 'ok', + detail: '', + tool: null, + decision: null, + error: entry.error, + }; +} + +function agentRow(record: AuditRecord, index: number): ActivityRow { + const known = DECISIONS[record.decision]; + // A call the engine allowed can still have failed when it ran. + const failedAfterAllow = record.error !== null && known?.tone === 'ok'; + const time = Date.parse(record.timestamp); + return { + key: `a-${record.timestamp}-${index}`, + time: Number.isNaN(time) ? 0 : time, + channel: 'agent', + mode: record.mode, + label: record.sql ?? record.tool, + sql: record.sql, + durationMs: record.durationMs, + rowCount: null, + kind: failedAfterAllow ? 'failed' : (known?.kind ?? 'other'), + outcome: failedAfterAllow ? 'Ran, with an error' : (known?.outcome ?? record.decision), + tone: failedAfterAllow ? 'error' : (known?.tone ?? 'muted'), + detail: [record.sql === null ? '' : record.tool, record.queryClass] + .filter((part) => part !== '') + .join(', '), + tool: record.tool, + decision: record.decision, + error: record.error, + }; +} + +/** Merges both records, newest first. */ +export function activityRows(activity: Activity): ActivityRow[] { + return [...activity.operator.map(operatorRow), ...activity.agent.map(agentRow)].sort( + (a, b) => b.time - a.time, + ); +} + +export interface ActivityFilter { + actor: 'all' | ActivityRow['channel']; + outcome: 'all' | OutcomeKind; +} + +export const NO_FILTER: ActivityFilter = { actor: 'all', outcome: 'all' }; + +/** The outcomes the list can be narrowed to, in the order they are offered. */ +export const OUTCOME_CHOICES: { value: OutcomeKind; label: string }[] = [ + { value: 'ran', label: 'Ran' }, + { value: 'failed', label: 'Failed' }, + { value: 'refused', label: 'Refused' }, + { value: 'approved', label: 'Approved' }, + { value: 'declined', label: 'Declined' }, + { value: 'stopped', label: 'Stopped waiting' }, +]; + +export function filterActivity(rows: ActivityRow[], filter: ActivityFilter): ActivityRow[] { + return rows.filter( + (row) => + (filter.actor === 'all' || row.channel === filter.actor) && + (filter.outcome === 'all' || row.kind === filter.outcome), + ); +} + +/** One JSON object on each line, in the order given. */ +export function activityJsonl(rows: ActivityRow[]): string { + return rows + .map((row) => + JSON.stringify({ + time: row.time === 0 ? null : new Date(row.time).toISOString(), + actor: row.channel, + mode: row.mode === '' ? null : row.mode, + statement: row.sql, + tool: row.tool, + durationMs: row.durationMs, + rows: row.rowCount, + outcome: row.kind, + decision: row.decision, + error: row.error, + }), + ) + .map((line) => `${line}\n`) + .join(''); +} + +export function formatTime(time: number): string { + if (time === 0) { + return ''; + } + const date = new Date(time); + const pad = (n: number) => String(n).padStart(2, '0'); + const clock = `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`; + const today = new Date(); + const sameDay = + date.getFullYear() === today.getFullYear() && + date.getMonth() === today.getMonth() && + date.getDate() === today.getDate(); + return sameDay + ? clock + : `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${clock}`; +} diff --git a/src/lib/cell.test.ts b/src/lib/cell.test.ts new file mode 100644 index 0000000..f8dcabd --- /dev/null +++ b/src/lib/cell.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from 'vitest'; +import { cellPreview, describeCell, looksLikeJson } from './cell'; + +describe('looksLikeJson', () => { + it('recognises objects and arrays by their brackets', () => { + expect(looksLikeJson('{"a":1}')).toBe(true); + expect(looksLikeJson('[]')).toBe(true); + expect(looksLikeJson('[1,2]')).toBe(true); + }); + + it('rejects everything else', () => { + expect(looksLikeJson(null)).toBe(false); + expect(looksLikeJson('')).toBe(false); + expect(looksLikeJson('{')).toBe(false); + expect(looksLikeJson('true')).toBe(false); + expect(looksLikeJson('42')).toBe(false); + expect(looksLikeJson('{oops]')).toBe(false); + expect(looksLikeJson('plain text')).toBe(false); + }); +}); + +describe('describeCell', () => { + it('reports a protocol null', () => { + expect(describeCell(null)).toEqual({ kind: 'null' }); + }); + + it('pretty-prints a JSON object', () => { + const cell = describeCell('{"bottle":true,"stable":"1.25.0"}'); + expect(cell.kind).toBe('json'); + if (cell.kind === 'json') { + expect(cell.pretty).toBe('{\n "bottle": true,\n "stable": "1.25.0"\n}'); + expect(cell.text).toBe('{"bottle":true,"stable":"1.25.0"}'); + } + }); + + it('pretty-prints a JSON array', () => { + const cell = describeCell('["a","b"]'); + expect(cell).toMatchObject({ kind: 'json', pretty: '[\n "a",\n "b"\n]' }); + }); + + it('treats text that only looks like JSON as text', () => { + expect(describeCell('{not json}')).toEqual({ kind: 'text', text: '{not json}' }); + expect(describeCell('[unterminated')).toEqual({ kind: 'text', text: '[unterminated' }); + }); + + it('treats scalars as text, as the engine sends them', () => { + expect(describeCell('true')).toEqual({ kind: 'text', text: 'true' }); + expect(describeCell('42')).toEqual({ kind: 'text', text: '42' }); + expect(describeCell('')).toEqual({ kind: 'text', text: '' }); + }); + + it('tolerates surrounding whitespace around JSON', () => { + expect(describeCell(' {"a":1}\n').kind).toBe('json'); + }); +}); + +describe('cellPreview', () => { + it('shows NULL for a protocol null', () => { + expect(cellPreview(null)).toBe('NULL'); + }); + + it('flattens whitespace to one line', () => { + expect(cellPreview('line one\n line two\ttabbed')).toBe('line one line two tabbed'); + }); + + it('cuts long values', () => { + expect(cellPreview('x'.repeat(1000))).toHaveLength(300); + }); + + it('leaves short values alone', () => { + expect(cellPreview('wget')).toBe('wget'); + expect(cellPreview('')).toBe(''); + }); +}); diff --git a/src/lib/cell.ts b/src/lib/cell.ts new file mode 100644 index 0000000..80795f9 --- /dev/null +++ b/src/lib/cell.ts @@ -0,0 +1,47 @@ +// How a grid cell is shown. The engine sends every value as text and gives +// no usable type information, so JSON is recognised by looking at the value. + +export type CellContent = + | { kind: 'null' } + | { kind: 'text'; text: string } + | { kind: 'json'; text: string; pretty: string }; + +/** Cheap check used while rendering the grid. Does not parse. */ +export function looksLikeJson(value: string | null): boolean { + if (value === null || value.length < 2) { + return false; + } + const first = value[0]; + const last = value[value.length - 1]; + return (first === '{' && last === '}') || (first === '[' && last === ']'); +} + +/** Full classification for the cell viewer. Parses the value once. */ +export function describeCell(value: string | null): CellContent { + if (value === null) { + return { kind: 'null' }; + } + const trimmed = value.trim(); + if (looksLikeJson(trimmed)) { + try { + const parsed: unknown = JSON.parse(trimmed); + if (typeof parsed === 'object' && parsed !== null) { + return { kind: 'json', text: value, pretty: JSON.stringify(parsed, null, 2) }; + } + } catch { + // Not JSON after all. Show it as text. + } + } + return { kind: 'text', text: value }; +} + +const PREVIEW_CHARS = 300; + +/** The text drawn in a grid cell: one line, cut to a sensible length. */ +export function cellPreview(value: string | null): string { + if (value === null) { + return 'NULL'; + } + const flat = value.length > PREVIEW_CHARS ? value.slice(0, PREVIEW_CHARS) : value; + return flat.replace(/\s+/g, ' '); +} diff --git a/src/lib/chart.test.ts b/src/lib/chart.test.ts new file mode 100644 index 0000000..474d4de --- /dev/null +++ b/src/lib/chart.test.ts @@ -0,0 +1,744 @@ +import { describe, expect, it } from 'vitest'; +import { + MAX_SERIES, + buildChart, + chartNumber, + chartTitle, + clip, + columnIndex, + formatTick, + formatValue, + neededColumns, + niceTicks, + parseChartSpec, + parseTime, + resolveChartData, + tableView, + timeTicks, + valueRange, + type CartesianModel, + type ChartData, + type ChartSpec, + type PieModel, +} from './chart'; + +function spec(source: object): ChartSpec { + const parsed = parseChartSpec(JSON.stringify(source)); + if (!parsed.ok) { + throw new Error(parsed.error); + } + return parsed.value; +} + +function cartesian(source: object, data: ChartData): CartesianModel { + const built = buildChart(spec(source), data); + if (!built.ok || built.value.kind !== 'cartesian') { + throw new Error(built.ok ? 'Not a cartesian chart.' : built.error); + } + return built.value; +} + +function pie(source: object, data: ChartData): PieModel { + const built = buildChart(spec(source), data); + if (!built.ok || built.value.kind !== 'pie') { + throw new Error(built.ok ? 'Not a pie chart.' : built.error); + } + return built.value; +} + +const errorOf = (outcome: { ok: true } | { ok: false; error: string }) => + outcome.ok ? null : outcome.error; + +const MONTHS: ChartData = { + columns: ['issues_created', 'month'], + rows: [ + ['1', '2023-01'], + ['46', '2023-10'], + ['13', '2026-10'], + ], +}; + +describe('parseChartSpec', () => { + it('reads the block a model is shown as the example', () => { + expect( + parseChartSpec( + '{"type": "bar", "title": "Issues created per month", "x": "month", "y": ["issues_created"]}', + ), + ).toEqual({ + ok: true, + value: { + type: 'bar', + title: 'Issues created per month', + x: 'month', + y: ['issues_created'], + series: null, + columns: null, + stacked: false, + horizontal: false, + xLabel: null, + yLabel: null, + data: null, + }, + }); + }); + + it('takes one y column written as text, and the other names a chart goes by', () => { + expect(spec({ type: 'Line', x: 'day', y: 'n' })).toMatchObject({ type: 'line', y: ['n'] }); + expect(spec({ type: 'column', x: 'a', y: ['b'] }).type).toBe('bar'); + expect(spec({ type: 'donut', x: 'a', y: ['b'] }).type).toBe('pie'); + }); + + it('reads the options', () => { + expect( + spec({ + type: 'bar', + x: 'region', + y: ['n'], + series: 'state', + stacked: true, + horizontal: true, + xLabel: 'Region', + yLabel: 'Instances', + }), + ).toMatchObject({ + series: 'state', + stacked: true, + horizontal: true, + xLabel: 'Region', + yLabel: 'Instances', + }); + // Only true turns an option on. + expect(spec({ type: 'bar', x: 'a', y: ['b'], stacked: 'yes' }).stacked).toBe(false); + }); + + it('says what is wrong with a block it cannot read', () => { + expect(errorOf(parseChartSpec('{"type": "bar", '))).toBe('The block is not valid JSON.'); + expect(errorOf(parseChartSpec('[1, 2]'))).toBe('The block must hold one JSON object.'); + expect(errorOf(parseChartSpec('{"type": "radar", "x": "a", "y": ["b"]}'))).toContain('"type"'); + expect(errorOf(parseChartSpec('{"x": "a", "y": ["b"]}'))).toContain('"type"'); + expect(errorOf(parseChartSpec('{"type": "bar", "y": ["b"]}'))).toContain('"x"'); + expect(errorOf(parseChartSpec('{"type": "bar", "x": "a"}'))).toContain('"y"'); + expect(errorOf(parseChartSpec('{"type": "bar", "x": "a", "y": [1]}'))).toContain('"y"'); + expect(errorOf(parseChartSpec('{"type": "bar", "x": "a", "y": []}'))).toContain('"y"'); + }); + + it('lets a table name no columns at all', () => { + expect(spec({ type: 'table' })).toMatchObject({ type: 'table', x: null, y: [], columns: null }); + expect(spec({ type: 'table', columns: ['name', 'region'] }).columns).toEqual([ + 'name', + 'region', + ]); + expect(errorOf(parseChartSpec('{"type": "table", "columns": "nope, really"}'))).toBeNull(); + expect(errorOf(parseChartSpec('{"type": "table", "columns": [1]}'))).toContain('"columns"'); + }); + + it('reads rows written in the block as the text a result set holds', () => { + const read = spec({ + type: 'bar', + x: 'month', + y: ['open', 'closed'], + data: [ + { month: '2026-01', open: 3, closed: 5 }, + { month: '2026-02', open: 4, extra: { nested: true } }, + ], + }); + expect(read.data).toEqual({ + columns: ['month', 'open', 'closed', 'extra'], + rows: [ + ['2026-01', '3', '5', null], + ['2026-02', '4', null, '{"nested":true}'], + ], + }); + }); + + it('also reads rows written as columns and rows', () => { + const read = spec({ + type: 'line', + x: 'd', + y: ['n'], + data: { + columns: ['d', 'n'], + rows: [ + ['2026-01-01', 2], + ['2026-01-02', null, 'ignored'], + ], + }, + }); + expect(read.data).toEqual({ + columns: ['d', 'n'], + rows: [ + ['2026-01-01', '2'], + ['2026-01-02', null], + ], + }); + }); + + it('refuses data that is not rows', () => { + expect(errorOf(parseChartSpec('{"type":"bar","x":"a","y":["b"],"data":"a,b"}'))).toContain( + '"data"', + ); + expect(errorOf(parseChartSpec('{"type":"bar","x":"a","y":["b"],"data":[1,2]}'))).toContain( + '"data"', + ); + expect( + errorOf(parseChartSpec('{"type":"bar","x":"a","y":["b"],"data":{"rows":[]}}')), + ).toContain('"data"'); + }); +}); + +describe('resolveChartData', () => { + const providers: ChartData = { columns: ['name', 'version'], rows: [['github', 'v1']] }; + const older: ChartData = { columns: ['month', 'issues_created'], rows: [['2020-01', '9']] }; + + it('draws from the most recent result set that has the columns', () => { + const chart = spec({ type: 'bar', x: 'month', y: ['issues_created'] }); + const resolved = resolveChartData(chart, [older, MONTHS, providers]); + expect(resolved).toEqual({ ok: true, value: { data: MONTHS, from: 1 } }); + }); + + it('matches a column whatever its case, and prefers the name as written', () => { + expect(columnIndex(['Month', 'month'], 'month')).toBe(1); + expect(columnIndex(['Month'], 'month')).toBe(0); + expect(columnIndex(['Month'], 'year')).toBe(-1); + const chart = spec({ type: 'bar', x: 'MONTH', y: ['Issues_Created'] }); + expect(resolveChartData(chart, [MONTHS])).toMatchObject({ ok: true, value: { from: 0 } }); + }); + + it('prefers rows written in the block', () => { + const chart = spec({ type: 'bar', x: 'month', y: ['n'], data: [{ month: '2026-01', n: 1 }] }); + const resolved = resolveChartData(chart, [MONTHS]); + expect(resolved.ok && resolved.value.from).toBeNull(); + expect(resolved.ok && resolved.value.data.rows).toEqual([['2026-01', '1']]); + }); + + it('says which columns it could not find', () => { + const chart = spec({ type: 'bar', x: 'week', y: ['issues_created'] }); + expect(errorOf(resolveChartData(chart, [MONTHS]))).toBe( + 'No result set in this conversation has the columns "week", "issues_created".', + ); + expect(errorOf(resolveChartData(chart, []))).toBe( + 'There is no result set in this conversation to draw from.', + ); + const inline = spec({ type: 'bar', x: 'week', y: ['n'], data: [{ month: 'x', n: 1 }] }); + expect(errorOf(resolveChartData(inline, [MONTHS]))).toBe( + 'The data in the block has no column "week".', + ); + }); + + it('gives a table with no columns named the latest result set', () => { + const resolved = resolveChartData(spec({ type: 'table' }), [MONTHS, providers]); + expect(resolved).toEqual({ ok: true, value: { data: providers, from: 1 } }); + expect(neededColumns(spec({ type: 'table' }))).toEqual([]); + expect(neededColumns(spec({ type: 'bar', x: 'a', y: ['b', 'a'], series: 'c' }))).toEqual([ + 'a', + 'b', + 'c', + ]); + }); +}); + +describe('tableView', () => { + it('shows the columns a table block asks for, in its order', () => { + const view = tableView( + spec({ type: 'table', columns: ['Month', 'nope', 'issues_created'] }), + MONTHS, + ); + expect(view.columns).toEqual(['month', 'issues_created']); + expect(view.rows[1]).toEqual(['2023-10', '46']); + }); + + it('shows everything otherwise', () => { + expect(tableView(spec({ type: 'table' }), MONTHS)).toBe(MONTHS); + expect(tableView(spec({ type: 'bar', x: 'month', y: ['issues_created'] }), MONTHS)).toBe( + MONTHS, + ); + }); +}); + +describe('chartNumber and parseTime', () => { + it('reads the numbers a result set holds as text', () => { + expect(chartNumber('46')).toBe(46); + expect(chartNumber('1,234,567.5')).toBe(1234567.5); + expect(chartNumber('45%')).toBe(45); + expect(chartNumber(' 3.5 ')).toBe(3.5); + expect(chartNumber('1,23')).toBeNull(); + expect(chartNumber('n/a')).toBeNull(); + expect(chartNumber('')).toBeNull(); + expect(chartNumber(null)).toBeNull(); + }); + + it('reads years, months, days and moments, in UTC', () => { + expect(parseTime('2026')).toBe(Date.UTC(2026, 0, 1)); + expect(parseTime('2026-11')).toBe(Date.UTC(2026, 10, 1)); + expect(parseTime('2026-11-16')).toBe(Date.UTC(2026, 10, 16)); + expect(parseTime('2026-11-16T01:40:36Z')).toBe(Date.UTC(2026, 10, 16, 1, 40, 36)); + expect(parseTime('2026-11-16 01:40')).toBe(Date.UTC(2026, 10, 16, 1, 40)); + expect(parseTime('2026-11-16T01:40:36+11:00')).toBe(Date.UTC(2026, 10, 15, 14, 40, 36)); + }); + + it('does not take other things for a time', () => { + for (const value of ['8080', '1500', '2026-13', '2026-00-10', 'November', '', '26-11-2026']) { + expect(parseTime(value), value).toBeNull(); + } + expect(parseTime(null)).toBeNull(); + }); +}); + +describe('a bar chart', () => { + it('draws one bar for each row, in the order of the rows', () => { + const model = cartesian({ type: 'bar', x: 'month', y: ['issues_created'] }, MONTHS); + expect(model).toMatchObject({ + type: 'bar', + xKind: 'category', + positions: null, + labels: ['2023-01', '2023-10', '2026-10'], + series: [{ name: 'issues_created', values: [1, 46, 13] }], + stacked: false, + horizontal: false, + notes: [], + }); + }); + + it('draws one series for each y column', () => { + const model = cartesian( + { type: 'bar', x: 'region', y: ['running', 'stopped'], stacked: true }, + { + columns: ['region', 'running', 'stopped'], + rows: [ + ['us-east-1', '12', '3'], + ['eu-west-1', '4', null], + ], + }, + ); + expect(model.series).toEqual([ + { name: 'running', values: [12, 4] }, + { name: 'stopped', values: [3, null] }, + ]); + expect(model.stacked).toBe(true); + }); + + it('does not stack one series', () => { + const model = cartesian( + { type: 'bar', x: 'month', y: ['issues_created'], stacked: true }, + MONTHS, + ); + expect(model.stacked).toBe(false); + }); + + it('turns rows that carry a series name into one series for each name', () => { + const model = cartesian( + { type: 'bar', x: 'month', y: ['n'], series: 'state' }, + { + columns: ['month', 'state', 'n'], + rows: [ + ['2026-10', 'open', '13'], + ['2026-10', 'closed', '20'], + ['2026-11', 'open', '8'], + // Rows that share a point are added together. + ['2026-10', 'open', '2'], + ], + }, + ); + expect(model.labels).toEqual(['2026-10', '2026-11']); + expect(model.series).toEqual([ + { name: 'open', values: [15, 8] }, + { name: 'closed', values: [20, null] }, + ]); + }); + + it('says what it left out', () => { + const model = cartesian( + { type: 'bar', x: 'name', y: ['size'] }, + { + columns: ['name', 'size'], + rows: [ + ['a', '10'], + ['b', 'unknown'], + ['c', ''], + ['d', null], + ], + }, + ); + expect(model.series[0]?.values).toEqual([10, null, null, null]); + expect(model.notes).toEqual(['1 value that is not a number was left out.']); + }); + + it('keeps the largest series and adds the rest together when there are too many', () => { + const names = Array.from({ length: 12 }, (_, index) => `s${index + 1}`); + const model = cartesian( + { type: 'bar', x: 'x', y: names }, + { columns: ['x', ...names], rows: [['only', ...names.map((_, index) => String(index + 1))]] }, + ); + expect(model.series).toHaveLength(MAX_SERIES); + expect(model.series.map((entry) => entry.name)).toEqual([ + 's6', + 's7', + 's8', + 's9', + 's10', + 's11', + 's12', + 'Other', + ]); + // 1 + 2 + 3 + 4 + 5 + expect(model.series[MAX_SERIES - 1]?.values).toEqual([15]); + expect(model.notes[0]).toContain('7 largest of 12 series'); + }); + + it('draws no more bars than can be told apart', () => { + const rows = Array.from({ length: 250 }, (_, index) => [`c${index}`, String(index)]); + const model = cartesian({ type: 'bar', x: 'c', y: ['n'] }, { columns: ['c', 'n'], rows }); + expect(model.labels).toHaveLength(200); + expect(model.notes).toEqual(['Showing the first 200 of 250 points.']); + // Bars that lie down take a row each, so fewer are drawn. + const down = cartesian( + { type: 'bar', x: 'c', y: ['n'], horizontal: true }, + { columns: ['c', 'n'], rows }, + ); + expect(down.labels).toHaveLength(25); + expect(down.notes).toEqual(['Showing the first 25 of 250 points.']); + }); +}); + +describe('a line chart', () => { + it('places dates where they fall in time, in order', () => { + const model = cartesian( + { type: 'line', x: 'month', y: ['issues_created'] }, + { + columns: ['month', 'issues_created'], + rows: [ + ['2026-10', '13'], + ['2023-01', '1'], + ['2023-10', '46'], + ], + }, + ); + expect(model.xKind).toBe('time'); + expect(model.labels).toEqual(['2023-01', '2023-10', '2026-10']); + expect(model.positions).toEqual([ + Date.UTC(2023, 0, 1), + Date.UTC(2023, 9, 1), + Date.UTC(2026, 9, 1), + ]); + expect(model.series[0]?.values).toEqual([1, 46, 13]); + }); + + it('places numbers where they fall on a scale', () => { + const model = cartesian( + { type: 'scatter', x: 'cpu', y: ['cost'] }, + { + columns: ['cpu', 'cost'], + rows: [ + ['8', '0.4'], + ['2', '0.1'], + ], + }, + ); + expect(model.xKind).toBe('number'); + expect(model.positions).toEqual([2, 8]); + expect(model.series[0]?.values).toEqual([0.1, 0.4]); + }); + + it('spaces names evenly when x is neither', () => { + const model = cartesian( + { type: 'area', x: 'region', y: ['n'] }, + { + columns: ['region', 'n'], + rows: [ + ['us', '1'], + ['eu', '2'], + ], + }, + ); + expect(model.xKind).toBe('category'); + expect(model.positions).toBeNull(); + expect(model.labels).toEqual(['us', 'eu']); + }); + + it('keeps each row of a scatter chart as a point of its own series', () => { + const model = cartesian( + { type: 'scatter', x: 'cpu', y: ['cost'], series: 'family' }, + { + columns: ['cpu', 'cost', 'family'], + rows: [ + ['2', '0.1', 'm'], + ['2', '0.2', 'c'], + ['4', '0.3', 'm'], + ], + }, + ); + expect(model.positions).toEqual([2, 2, 4]); + expect(model.series).toEqual([ + { name: 'm', values: [0.1, null, 0.3] }, + { name: 'c', values: [null, 0.2, null] }, + ]); + }); +}); + +describe('a pie chart', () => { + it('adds up the rows of each part', () => { + const model = pie( + { type: 'pie', x: 'state', y: ['n'] }, + { + columns: ['state', 'n'], + rows: [ + ['open', '97'], + ['closed', '300'], + ['open', '3'], + ], + }, + ); + expect(model.slices).toEqual([ + { name: 'open', value: 100 }, + { name: 'closed', value: 300 }, + ]); + expect(model.total).toBe(400); + expect(model.valueName).toBe('n'); + }); + + it('leaves out what is not above zero, and says so', () => { + const model = pie( + { type: 'pie', x: 'k', y: ['n'] }, + { + columns: ['k', 'n'], + rows: [ + ['a', '5'], + ['b', '0'], + ['c', '-2'], + ['d', 'x'], + ], + }, + ); + expect(model.slices).toEqual([{ name: 'a', value: 5 }]); + expect(model.notes).toEqual(['3 rows with no amount above zero were left out.']); + }); + + it('keeps the largest parts and adds the rest together', () => { + const rows = Array.from({ length: 10 }, (_, index) => [`p${index + 1}`, String(index + 1)]); + const model = pie({ type: 'pie', x: 'p', y: ['n'] }, { columns: ['p', 'n'], rows }); + expect(model.slices.map((slice) => slice.name)).toEqual([ + 'p10', + 'p9', + 'p8', + 'p7', + 'p6', + 'p5', + 'p4', + 'Other', + ]); + // 1 + 2 + 3 + expect(model.slices[7]?.value).toBe(6); + expect(model.total).toBe(55); + }); +}); + +describe('a chart with nothing to draw', () => { + it('says so in place of an empty frame', () => { + const bars = spec({ type: 'bar', x: 'month', y: ['issues_created'] }); + expect(errorOf(buildChart(bars, { columns: MONTHS.columns, rows: [] }))).toBe( + 'There is nothing to draw: the result set has no rows.', + ); + expect( + errorOf(buildChart(bars, { columns: MONTHS.columns, rows: [['many', '2023-01']] })), + ).toBe('There is nothing to draw: "issues_created" holds no numbers.'); + expect( + errorOf( + buildChart(spec({ type: 'pie', x: 'month', y: ['issues_created'] }), { + columns: MONTHS.columns, + rows: [['0', '2023-01']], + }), + ), + ).toContain('no amounts above zero'); + expect(errorOf(buildChart(spec({ type: 'table' }), MONTHS))).toBe('A table is not a chart.'); + }); +}); + +describe('niceTicks', () => { + it('covers the range with round values', () => { + expect(niceTicks(0, 46)).toEqual([0, 10, 20, 30, 40, 50]); + expect(niceTicks(0, 97)).toEqual([0, 20, 40, 60, 80, 100]); + expect(niceTicks(-3, 7)).toEqual([-4, -2, 0, 2, 4, 6, 8]); + expect(niceTicks(0, 1234567)).toEqual([0, 500000, 1000000, 1500000]); + }); + + it('does not drift on small steps', () => { + expect(niceTicks(0, 0.5)).toEqual([0, 0.1, 0.2, 0.3, 0.4, 0.5]); + }); + + it('still makes an axis for one value, or none', () => { + expect(niceTicks(0, 0)).toEqual([0, 1]); + expect(niceTicks(8, 8)).toEqual([0, 2, 4, 6, 8]); + expect(niceTicks(-8, -8)).toEqual([-8, -6, -4, -2, 0]); + expect(niceTicks(NaN, 3)).toEqual([0, 1]); + }); +}); + +describe('valueRange', () => { + const model = (type: CartesianModel['type'], values: (number | null)[][], stacked = false) => + ({ + kind: 'cartesian', + type, + labels: values[0]?.map((_, index) => String(index)) ?? [], + positions: null, + xKind: 'category', + series: values.map((entries, index) => ({ name: `s${index}`, values: entries })), + stacked, + horizontal: false, + notes: [], + }) satisfies CartesianModel; + + it('starts bars and areas at zero', () => { + expect(valueRange(model('bar', [[40, 46]]))).toEqual([0, 46]); + expect(valueRange(model('area', [[40, 46]]))).toEqual([0, 46]); + expect(valueRange(model('bar', [[-5, 3]]))).toEqual([-5, 3]); + }); + + it('keeps zero on a line only when it is near', () => { + expect(valueRange(model('line', [[10, 46]]))).toEqual([0, 46]); + expect(valueRange(model('line', [[990, 1010]]))).toEqual([990, 1010]); + }); + + it('adds stacked values up, above and below zero apart', () => { + expect( + valueRange( + model( + 'bar', + [ + [10, -2], + [5, -3], + ], + true, + ), + ), + ).toEqual([-5, 15]); + }); + + it('copes with nothing but gaps', () => { + expect(valueRange(model('line', [[null, null]]))).toEqual([0, 1]); + }); +}); + +describe('formatTick and formatValue', () => { + it('writes an axis in full under ten thousand', () => { + const ticks = [0, 2000, 4000, 6000, 8000]; + expect(ticks.map((tick) => formatTick(tick, ticks))).toEqual([ + '0', + '2,000', + '4,000', + '6,000', + '8,000', + ]); + }); + + it('writes an axis short once it reaches ten thousand, one style for the whole axis', () => { + const thousands = [0, 5000, 10000, 15000]; + expect(thousands.map((tick) => formatTick(tick, thousands))).toEqual([ + '0K', + '5K', + '10K', + '15K', + ]); + const millions = [0, 500000, 1000000, 1500000]; + expect(millions.map((tick) => formatTick(tick, millions))).toEqual([ + '0.0M', + '0.5M', + '1.0M', + '1.5M', + ]); + }); + + it('keeps the decimals a small step needs', () => { + const tenths = niceTicks(0, 0.5); + expect(tenths.map((tick) => formatTick(tick, tenths))).toEqual([ + '0.0', + '0.1', + '0.2', + '0.3', + '0.4', + '0.5', + ]); + const hundredths = [0, 0.05, 0.1]; + expect(hundredths.map((tick) => formatTick(tick, hundredths))).toEqual([ + '0.00', + '0.05', + '0.10', + ]); + }); + + it('writes a value in full for a tooltip', () => { + expect(formatValue(1234567)).toBe('1,234,567'); + expect(formatValue(1234.5678)).toBe('1,234.6'); + expect(formatValue(3.14159)).toBe('3.14'); + expect(formatValue(0.012345)).toBe('0.0123'); + }); +}); + +describe('timeTicks', () => { + const labels = (min: number, max: number) => timeTicks(min, max).map((tick) => tick.label); + + it('marks years over a span of years', () => { + expect(labels(Date.UTC(2023, 0, 1), Date.UTC(2026, 10, 1))).toEqual([ + '2023', + '2024', + '2025', + '2026', + ]); + }); + + it('marks months over a span of months, counted from January', () => { + expect(labels(Date.UTC(2026, 0, 15), Date.UTC(2026, 10, 1))).toEqual([ + 'Mar 2026', + 'May 2026', + 'Jul 2026', + 'Sep 2026', + 'Nov 2026', + ]); + }); + + it('marks days over a span of days, and hours within a day', () => { + expect(labels(Date.UTC(2026, 10, 10), Date.UTC(2026, 10, 16))).toEqual([ + '10 Nov', + '11 Nov', + '12 Nov', + '13 Nov', + '14 Nov', + '15 Nov', + '16 Nov', + ]); + expect(labels(Date.UTC(2026, 10, 16, 0), Date.UTC(2026, 10, 16, 12))).toEqual([ + '00:00', + '02:00', + '04:00', + '06:00', + '08:00', + '10:00', + '12:00', + ]); + }); + + it('keeps every tick inside the span', () => { + const min = Date.UTC(2024, 5, 20); + const max = Date.UTC(2025, 1, 3); + for (const tick of timeTicks(min, max)) { + expect(tick.value).toBeGreaterThanOrEqual(min); + expect(tick.value).toBeLessThanOrEqual(max); + } + }); +}); + +describe('clip and chartTitle', () => { + it('cuts a label to fit', () => { + expect(clip('us-east-1', 20)).toBe('us-east-1'); + expect(clip('a-very-long-resource-name', 12)).toBe('a-very-lo...'); + }); + + it('names a chart after its columns when the block gave no title', () => { + expect(chartTitle(spec({ type: 'bar', x: 'month', y: ['open', 'closed'] }))).toBe( + 'open, closed by month', + ); + expect(chartTitle(spec({ type: 'bar', title: 'Velocity', x: 'month', y: ['n'] }))).toBe( + 'Velocity', + ); + expect(chartTitle(spec({ type: 'table' }))).toBe('Result'); + }); +}); diff --git a/src/lib/chart.ts b/src/lib/chart.ts new file mode 100644 index 0000000..30df6de --- /dev/null +++ b/src/lib/chart.ts @@ -0,0 +1,807 @@ +// The chart block: what a model writes to ask for a chart, and what is +// worked out from it before anything is drawn. Pure functions. +// +// A model puts a fenced block with the language `chart` in its answer. The +// block holds one JSON object that names a chart type and the columns to +// draw. The rows come from a result set already in the conversation, or +// from the block itself. Nothing in a block is ever run or turned into +// markup: it is read as data, checked, and drawn by this app's own code. +// +// The format is described for a model in `src-tauri/src/agent/guidance.rs` +// and for people in `docs/charts.md`. Keep the three in step. + +import type { Row } from '../host/types'; +import { cellNumber } from './sortRows'; + +export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'scatter' | 'table'; + +const TYPES: Record = { + bar: 'bar', + column: 'bar', + line: 'line', + area: 'area', + pie: 'pie', + donut: 'pie', + doughnut: 'pie', + scatter: 'scatter', + table: 'table', +}; + +export interface ChartData { + columns: string[]; + rows: Row[]; +} + +export interface ChartSpec { + type: ChartType; + title: string | null; + /** The column along the horizontal axis, or the one that names the slices. */ + x: string | null; + /** The columns that hold the numbers. */ + y: string[]; + /** A column whose values name the series, for rows that carry one. */ + series: string | null; + /** For a table: the columns to show, in order. Null shows them all. */ + columns: string[] | null; + stacked: boolean; + horizontal: boolean; + xLabel: string | null; + yLabel: string | null; + /** Rows given in the block itself. */ + data: ChartData | null; +} + +export type Outcome = { ok: true; value: T } | { ok: false; error: string }; + +const fail = (error: string): { ok: false; error: string } => ({ ok: false, error }); + +/** Rows a block may carry, and points a chart will draw. */ +export const MAX_INLINE_ROWS = 5000; +/** A chart never has more series than the palette has colours. */ +export const MAX_SERIES = 8; +const MAX_BARS = 200; +const MAX_ROWS_OF_BARS = 25; +const MAX_POINTS = 2000; + +function text(value: unknown): string | null { + return typeof value === 'string' && value.trim() !== '' ? value.trim() : null; +} + +function names(value: unknown): string[] | null { + if (typeof value === 'string') { + return value.trim() === '' ? null : [value.trim()]; + } + if (Array.isArray(value)) { + const list = value.flatMap((entry) => + typeof entry === 'string' && entry.trim() ? [entry.trim()] : [], + ); + return list.length === value.length && list.length > 0 ? list : null; + } + return null; +} + +/** One value of a block's own data, as the text a result set would hold. */ +function cell(value: unknown): string | null { + if (value === null || value === undefined) { + return null; + } + if (typeof value === 'string') { + return value; + } + if (typeof value === 'number' || typeof value === 'boolean') { + return String(value); + } + return JSON.stringify(value); +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +/** Rows written in the block: a list of objects, or columns with rows. */ +function inlineData(value: unknown): Outcome { + if (Array.isArray(value)) { + const records = value.slice(0, MAX_INLINE_ROWS); + if (!records.every(isRecord)) { + return fail('"data" must be a list of objects, one for each row.'); + } + const columns: string[] = []; + for (const record of records) { + for (const key of Object.keys(record)) { + if (!columns.includes(key)) { + columns.push(key); + } + } + } + return { + ok: true, + value: { columns, rows: records.map((record) => columns.map((name) => cell(record[name]))) }, + }; + } + if (isRecord(value)) { + const columns = names(value.columns); + const rows = value.rows; + if (!columns || !Array.isArray(rows) || !rows.every((row) => Array.isArray(row))) { + return fail('"data" must be a list of objects, one for each row.'); + } + return { + ok: true, + value: { + columns, + rows: rows + .slice(0, MAX_INLINE_ROWS) + .map((row) => columns.map((_, index) => cell((row as unknown[])[index]))), + }, + }; + } + return fail('"data" must be a list of objects, one for each row.'); +} + +/** Reads the text of a chart block. Anything that is not understood is an error, not a guess. */ +export function parseChartSpec(source: string): Outcome { + let raw: unknown; + try { + raw = JSON.parse(source); + } catch { + return fail('The block is not valid JSON.'); + } + if (!isRecord(raw)) { + return fail('The block must hold one JSON object.'); + } + const type = typeof raw.type === 'string' ? TYPES[raw.type.trim().toLowerCase()] : undefined; + if (!type) { + return fail('"type" must be one of bar, line, area, pie, scatter and table.'); + } + const x = text(raw.x); + const y = raw.y === undefined || raw.y === null ? [] : names(raw.y); + if (y === null) { + return fail('"y" must name one or more columns.'); + } + if (type !== 'table') { + if (x === null) { + return fail('"x" must name a column.'); + } + if (y.length === 0) { + return fail('"y" must name one or more columns.'); + } + } + let columns: string[] | null = null; + if (raw.columns !== undefined && raw.columns !== null) { + columns = names(raw.columns); + if (columns === null) { + return fail('"columns" must be a list of column names.'); + } + } + let data: ChartData | null = null; + if (raw.data !== undefined && raw.data !== null) { + const read = inlineData(raw.data); + if (!read.ok) { + return read; + } + data = read.value; + } + return { + ok: true, + value: { + type, + title: text(raw.title), + x, + y, + series: text(raw.series), + columns, + stacked: raw.stacked === true, + horizontal: raw.horizontal === true, + xLabel: text(raw.xLabel), + yLabel: text(raw.yLabel), + data, + }, + }; +} + +/** Where a named column is. The name as written wins over one that differs only in case. */ +export function columnIndex(columns: string[], name: string): number { + const exact = columns.indexOf(name); + if (exact >= 0) { + return exact; + } + const lower = name.toLowerCase(); + return columns.findIndex((column) => column.toLowerCase() === lower); +} + +/** The columns a block names, which the data it is drawn from must have. */ +export function neededColumns(spec: ChartSpec): string[] { + const list = + spec.type === 'table' + ? (spec.columns ?? []) + : [ + ...(spec.x === null ? [] : [spec.x]), + ...spec.y, + ...(spec.series === null ? [] : [spec.series]), + ]; + return [...new Set(list)]; +} + +const quoted = (list: string[]) => list.map((name) => `"${name}"`).join(', '); + +export interface ResolvedData { + data: ChartData; + /** Which of the result sets the rows came from. Null when the block carried them. */ + from: number | null; +} + +/** + * Finds the rows a block is drawn from: its own, or the most recent result + * set that has every column it names. `results` is oldest first. + */ +export function resolveChartData(spec: ChartSpec, results: ChartData[]): Outcome { + const needed = neededColumns(spec); + const has = (data: ChartData) => needed.every((name) => columnIndex(data.columns, name) >= 0); + if (spec.data) { + const missing = needed.filter((name) => columnIndex(spec.data?.columns ?? [], name) < 0); + return missing.length === 0 + ? { ok: true, value: { data: spec.data, from: null } } + : fail(`The data in the block has no column ${quoted(missing)}.`); + } + for (let index = results.length - 1; index >= 0; index -= 1) { + const candidate = results[index]; + if (candidate && has(candidate)) { + return { ok: true, value: { data: candidate, from: index } }; + } + } + if (results.length === 0) { + return fail('There is no result set in this conversation to draw from.'); + } + return fail(`No result set in this conversation has the columns ${quoted(needed)}.`); +} + +/** The columns a table block asks for, or all of them. */ +export function tableView(spec: ChartSpec, data: ChartData): ChartData { + if (spec.type !== 'table' || spec.columns === null) { + return data; + } + const picked = spec.columns + .map((name) => columnIndex(data.columns, name)) + .filter((at) => at >= 0); + return { + columns: picked.map((at) => data.columns[at] ?? ''), + rows: data.rows.map((row) => picked.map((at) => row[at] ?? null)), + }; +} + +const GROUPED = /^[+-]?\d{1,3}(?:,\d{3})+(?:\.\d+)?$/; + +/** The number in a cell. Also reads 1,234 and 45%, which a result can hold as text. */ +export function chartNumber(value: string | null | undefined): number | null { + if (value === null || value === undefined) { + return null; + } + let candidate = value.trim(); + if (candidate.endsWith('%')) { + candidate = candidate.slice(0, -1).trim(); + } + if (GROUPED.test(candidate)) { + candidate = candidate.replace(/,/g, ''); + } + return cellNumber(candidate); +} + +const DATE = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/; +const DATE_TIME = + /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?\s*(Z|[+-]\d{2}:?\d{2})?$/i; + +/** + * The moment a cell names, in milliseconds since 1970, for the forms a + * result set holds: a year, a month, a day, or a date with a time. A time + * with no zone is taken as UTC, so that a chart does not move with the + * operator's own zone. + */ +export function parseTime(value: string | null | undefined): number | null { + if (value === null || value === undefined) { + return null; + } + const source = value.trim(); + const date = DATE.exec(source); + if (date) { + const year = Number(date[1]); + const month = date[2] === undefined ? 1 : Number(date[2]); + const day = date[3] === undefined ? 1 : Number(date[3]); + if (year < 1900 || year > 2100 || month < 1 || month > 12 || day < 1 || day > 31) { + return null; + } + return Date.UTC(year, month - 1, day); + } + const moment = DATE_TIME.exec(source); + if (moment) { + const zone = moment[7] ? moment[7].toUpperCase() : 'Z'; + const parsed = Date.parse( + `${moment[1]}-${moment[2]}-${moment[3]}T${moment[4]}:${moment[5]}:${moment[6] ?? '00'}${zone}`, + ); + return Number.isNaN(parsed) ? null : parsed; + } + return null; +} + +export interface Series { + name: string; + /** One value for each position along the axis. Null where there is none. */ + values: (number | null)[]; +} + +export interface CartesianModel { + kind: 'cartesian'; + type: 'bar' | 'line' | 'area' | 'scatter'; + /** What each position along the axis is called. */ + labels: string[]; + /** Where each position sits on a continuous axis. Null spaces them evenly. */ + positions: number[] | null; + xKind: 'category' | 'time' | 'number'; + series: Series[]; + stacked: boolean; + horizontal: boolean; + /** What was left out or put together, said under the chart. */ + notes: string[]; +} + +export interface PieModel { + kind: 'pie'; + slices: { name: string; value: number }[]; + total: number; + /** What the slices measure. */ + valueName: string; + notes: string[]; +} + +export type ChartModel = CartesianModel | PieModel; + +const OTHER = 'Other'; + +const plural = (count: number, one: string, many: string) => + `${count.toLocaleString('en-US')} ${count === 1 ? one : many}`; + +/** Keeps the largest series and adds the rest together, so that a chart never runs out of colours. */ +function capSeries(series: Series[], notes: string[]): Series[] { + if (series.length <= MAX_SERIES) { + return series; + } + const size = (entry: Series) => + entry.values.reduce((sum, v) => sum + Math.abs(v ?? 0), 0); + const ranked = series.map((entry, index) => ({ entry, index, size: size(entry) })); + const keep = new Set( + [...ranked] + .sort((a, b) => b.size - a.size || a.index - b.index) + .slice(0, MAX_SERIES - 1) + .map((item) => item.index), + ); + const kept = series.filter((_, index) => keep.has(index)); + const rest = series.filter((_, index) => !keep.has(index)); + const length = series[0]?.values.length ?? 0; + const other: Series = { + name: OTHER, + values: Array.from({ length }, (_, at) => { + const present = rest.flatMap((entry) => { + const value = entry.values[at]; + return value === null || value === undefined ? [] : [value]; + }); + return present.length === 0 ? null : present.reduce((sum, value) => sum + value, 0); + }), + }; + notes.push( + `Showing the ${MAX_SERIES - 1} largest of ${series.length} series. The rest are added together as ${OTHER}.`, + ); + return [...kept, other]; +} + +function buildPie(spec: ChartSpec, data: ChartData): Outcome { + const labelAt = columnIndex(data.columns, spec.x ?? ''); + const valueName = spec.y[0] ?? ''; + const valueAt = columnIndex(data.columns, valueName); + const notes: string[] = []; + const totals = new Map(); + let skipped = 0; + for (const row of data.rows) { + const value = chartNumber(row[valueAt]); + if (value === null || value <= 0) { + skipped += 1; + continue; + } + const name = row[labelAt] ?? '(none)'; + totals.set(name, (totals.get(name) ?? 0) + value); + } + if (skipped > 0) { + notes.push( + `${plural(skipped, 'row', 'rows')} with no amount above zero ${skipped === 1 ? 'was' : 'were'} left out.`, + ); + } + let slices = [...totals].map(([name, value]) => ({ name, value })); + if (slices.length === 0) { + return fail(`There is nothing to draw: "${valueName}" holds no amounts above zero.`); + } + if (slices.length > MAX_SERIES) { + const ranked = [...slices].sort((a, b) => b.value - a.value); + const kept = ranked.slice(0, MAX_SERIES - 1); + const rest = ranked.slice(MAX_SERIES - 1).reduce((sum, slice) => sum + slice.value, 0); + notes.push( + `Showing the ${MAX_SERIES - 1} largest of ${slices.length} parts. The rest are added together as ${OTHER}.`, + ); + slices = [...kept, { name: OTHER, value: rest }]; + } + return { + ok: true, + value: { + kind: 'pie', + slices, + total: slices.reduce((sum, slice) => sum + slice.value, 0), + valueName, + notes, + }, + }; +} + +interface Draft { + labels: string[]; + series: Series[]; +} + +/** Rows that carry a series name: one position for each x, one series for each name. */ +function pivot( + data: ChartData, + xAt: number, + yAt: number, + seriesAt: number, + merge: boolean, +): Draft & { unread: number } { + const labels: string[] = []; + const position = new Map(); + const series = new Map(); + let unread = 0; + data.rows.forEach((row) => { + const label = row[xAt] ?? ''; + let at: number; + const known = merge ? position.get(label) : undefined; + if (known === undefined) { + at = labels.length; + labels.push(label); + position.set(label, at); + } else { + at = known; + } + const name = row[seriesAt] ?? '(none)'; + const values = series.get(name) ?? []; + series.set(name, values); + const raw = row[yAt]; + const value = chartNumber(raw); + if (value === null) { + if (raw !== null && raw !== undefined && raw.trim() !== '') { + unread += 1; + } + return; + } + // Rows that share a point are added together. + values[at] = (values[at] ?? 0) + value; + }); + return { + labels, + series: [...series].map(([name, values]) => ({ + name, + values: Array.from({ length: labels.length }, (_, at) => values[at] ?? null), + })), + unread, + }; +} + +/** Works out what to draw. An error says why nothing can be. */ +export function buildChart(spec: ChartSpec, data: ChartData): Outcome { + if (spec.type === 'table') { + return fail('A table is not a chart.'); + } + if (data.rows.length === 0) { + return fail('There is nothing to draw: the result set has no rows.'); + } + if (spec.type === 'pie') { + return buildPie(spec, data); + } + + const type = spec.type; + const notes: string[] = []; + const xAt = columnIndex(data.columns, spec.x ?? ''); + let draft: Draft; + let unread = 0; + + if (spec.series !== null) { + if (spec.y.length > 1) { + notes.push(`With a series column only "${spec.y[0] ?? ''}" is drawn.`); + } + const pivoted = pivot( + data, + xAt, + columnIndex(data.columns, spec.y[0] ?? ''), + columnIndex(data.columns, spec.series), + // Each row of a scatter chart is a point of its own. + type !== 'scatter', + ); + draft = pivoted; + unread = pivoted.unread; + } else { + draft = { + labels: data.rows.map((row) => row[xAt] ?? ''), + series: spec.y.map((name) => { + const at = columnIndex(data.columns, name); + return { + name, + values: data.rows.map((row) => { + const raw = row[at]; + const value = chartNumber(raw); + if (value === null && raw !== null && raw !== undefined && raw.trim() !== '') { + unread += 1; + } + return value; + }), + }; + }), + }; + } + if (unread > 0) { + notes.push( + `${plural(unread, 'value that is not a number was', 'values that are not numbers were')} left out.`, + ); + } + + // A line follows its axis, so the positions of a continuous axis are put in order. + let xKind: CartesianModel['xKind'] = 'category'; + let positions: number[] | null = null; + if (type !== 'bar') { + const asTime = draft.labels.map(parseTime); + const asNumber = draft.labels.map(chartNumber); + if (asTime.every((value) => value !== null)) { + xKind = 'time'; + positions = asTime; + } else if (asNumber.every((value) => value !== null)) { + xKind = 'number'; + positions = asNumber; + } + } + if (positions) { + const where = positions; + const order = where + .map((_, index) => index) + .sort((a, b) => (where[a] ?? 0) - (where[b] ?? 0) || a - b); + draft = { + labels: order.map((index) => draft.labels[index] ?? ''), + series: draft.series.map((entry) => ({ + name: entry.name, + values: order.map((index) => entry.values[index] ?? null), + })), + }; + positions = order.map((index) => where[index] ?? 0); + } + + // Bars that lie down each take a row, so fewer of them fit a card. + const limit = type !== 'bar' ? MAX_POINTS : spec.horizontal ? MAX_ROWS_OF_BARS : MAX_BARS; + if (draft.labels.length > limit) { + notes.push( + `Showing the first ${limit.toLocaleString('en-US')} of ${draft.labels.length.toLocaleString('en-US')} points.`, + ); + draft = { + labels: draft.labels.slice(0, limit), + series: draft.series.map((entry) => ({ + name: entry.name, + values: entry.values.slice(0, limit), + })), + }; + positions = positions ? positions.slice(0, limit) : null; + } + + const series = capSeries(draft.series, notes); + if (!series.some((entry) => entry.values.some((value) => value !== null))) { + return fail( + `There is nothing to draw: ${quoted(spec.y)} ${spec.y.length === 1 ? 'holds' : 'hold'} no numbers.`, + ); + } + return { + ok: true, + value: { + kind: 'cartesian', + type, + labels: draft.labels, + positions, + xKind, + series, + stacked: type === 'bar' && spec.stacked && series.length > 1, + horizontal: type === 'bar' && spec.horizontal, + notes, + }, + }; +} + +/** The step between ticks: 1, 2 or 5 times a power of ten. */ +function niceStep(rough: number): number { + const power = Math.pow(10, Math.floor(Math.log10(rough))); + const fraction = rough / power; + const nice = fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 5 ? 5 : 10; + return nice * power; +} + +/** Round values that cover `min` to `max`, about `target` of them. The first and last are the ends of the axis. */ +export function niceTicks(min: number, max: number, target = 5): number[] { + if (!Number.isFinite(min) || !Number.isFinite(max)) { + return [0, 1]; + } + if (min === max) { + // One value: an axis around it, from zero when that is close. + if (min === 0) { + return [0, 1]; + } + return min > 0 ? niceTicks(0, min, target) : niceTicks(min, 0, target); + } + const step = niceStep((max - min) / Math.max(1, target)); + const first = Math.floor(min / step) * step; + const last = Math.ceil(max / step) * step; + const ticks: number[] = []; + // Counted, not added up, so that a step such as 0.1 does not drift. + const count = Math.round((last - first) / step); + for (let index = 0; index <= count; index += 1) { + ticks.push(Number((first + index * step).toPrecision(12))); + } + return ticks; +} + +/** + * The range of values an axis has to cover. Bars and areas grow from zero, + * so zero is always on their axis. A line keeps zero when it is near. + */ +export function valueRange(model: CartesianModel): [number, number] { + let min = Infinity; + let max = -Infinity; + const count = model.labels.length; + if (model.stacked) { + for (let at = 0; at < count; at += 1) { + let up = 0; + let down = 0; + for (const entry of model.series) { + const value = entry.values[at] ?? 0; + if (value >= 0) { + up += value; + } else { + down += value; + } + } + min = Math.min(min, down); + max = Math.max(max, up); + } + } else { + for (const entry of model.series) { + for (const value of entry.values) { + if (value !== null) { + min = Math.min(min, value); + max = Math.max(max, value); + } + } + } + } + if (!Number.isFinite(min) || !Number.isFinite(max)) { + return [0, 1]; + } + const fromZero = model.type === 'bar' || model.type === 'area' || (min >= 0 && min <= max / 2); + return fromZero ? [Math.min(min, 0), Math.max(max, 0)] : [min, max]; +} + +/** A value as an axis writes it: in full under ten thousand, and short above. */ +export function formatTick(value: number, ticks: number[]): string { + const reach = Math.max(...ticks.map((tick) => Math.abs(tick)), 0); + const step = ticks.length > 1 ? Math.abs((ticks[1] ?? 0) - (ticks[0] ?? 0)) : 1; + if (reach >= 10_000) { + const units: [number, string][] = [ + [1e12, 'T'], + [1e9, 'B'], + [1e6, 'M'], + [1e3, 'K'], + ]; + for (const [size, suffix] of units) { + if (reach >= size) { + const scaled = value / size; + const decimals = step / size >= 1 ? 0 : step / size >= 0.1 ? 1 : 2; + return `${scaled.toFixed(decimals)}${suffix}`; + } + } + } + const decimals = step >= 1 ? 0 : Math.min(6, Math.ceil(-Math.log10(step))); + return value.toLocaleString('en-US', { + minimumFractionDigits: decimals, + maximumFractionDigits: decimals, + }); +} + +/** A value as a tooltip or a legend writes it: in full. */ +export function formatValue(value: number): string { + const digits = Number.isInteger(value) + ? 0 + : Math.abs(value) >= 100 + ? 1 + : Math.abs(value) >= 1 + ? 2 + : 4; + return value.toLocaleString('en-US', { maximumFractionDigits: digits }); +} + +const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']; +const DAY = 86_400_000; +const two = (value: number) => String(value).padStart(2, '0'); + +export interface Tick { + value: number; + label: string; +} + +/** Ticks along a time axis, on years, months, days or hours as the span asks. */ +export function timeTicks(min: number, max: number, target = 6): Tick[] { + const span = Math.max(max - min, 1); + const first = new Date(min); + const ticks: Tick[] = []; + const month = (date: Date) => MONTHS[date.getUTCMonth()] ?? ''; + + if (span > 2 * 365 * DAY) { + const years = span / (365 * DAY); + const step = Math.max(1, niceStep(years / target)); + for (let year = Math.ceil(first.getUTCFullYear() / step) * step; ; year += step) { + const value = Date.UTC(year, 0, 1); + if (value > max) { + break; + } + if (value >= min) { + ticks.push({ value, label: String(year) }); + } + } + } else if (span > 60 * DAY) { + const months = span / (30.4 * DAY); + const step = [1, 2, 3, 6, 12].find((candidate) => months / candidate <= target) ?? 12; + let year = first.getUTCFullYear(); + let index = Math.ceil(first.getUTCMonth() / step) * step; + for (;;) { + const value = Date.UTC(year, index, 1); + if (value > max) { + break; + } + if (value >= min) { + const date = new Date(value); + ticks.push({ value, label: `${month(date)} ${date.getUTCFullYear()}` }); + } + index += step; + if (index >= 12) { + year += Math.floor(index / 12); + index %= 12; + } + } + } else if (span > 2 * DAY) { + const step = Math.max(1, Math.ceil(span / DAY / target)) * DAY; + for (let value = Math.ceil(min / DAY) * DAY; value <= max; value += step) { + const date = new Date(value); + ticks.push({ value, label: `${date.getUTCDate()} ${month(date)}` }); + } + } else { + const hour = 3_600_000; + const step = + ([1, 2, 3, 6, 12, 24].find((candidate) => span / hour / candidate <= target) ?? 24) * hour; + for (let value = Math.ceil(min / step) * step; value <= max; value += step) { + const date = new Date(value); + ticks.push({ value, label: `${two(date.getUTCHours())}:${two(date.getUTCMinutes())}` }); + } + } + return ticks; +} + +/** Text cut to a length, for a label that has to fit a space. */ +export function clip(label: string, maxChars: number): string { + return label.length > maxChars ? `${label.slice(0, Math.max(1, maxChars - 3))}...` : label; +} + +/** What a chart is called when the block gave it no title. */ +export function chartTitle(spec: ChartSpec): string { + if (spec.title !== null) { + return spec.title; + } + if (spec.type === 'table') { + return 'Result'; + } + const measured = spec.y.join(', '); + return spec.x === null ? measured : `${measured} by ${spec.x}`; +} diff --git a/src/lib/chartLayout.test.ts b/src/lib/chartLayout.test.ts new file mode 100644 index 0000000..fceb82b --- /dev/null +++ b/src/lib/chartLayout.test.ts @@ -0,0 +1,381 @@ +import { describe, expect, it } from 'vitest'; +import type { CartesianModel, PieModel } from './chart'; +import { + CHART_HEIGHT, + barPath, + formatShare, + layoutCartesian, + layoutPie, + nearestPoint, + nearestPosition, +} from './chartLayout'; + +const UNTITLED = { x: false, y: false }; + +function model(over: Partial & Pick): CartesianModel { + const count = over.series[0]?.values.length ?? 0; + return { + kind: 'cartesian', + type: 'bar', + labels: Array.from({ length: count }, (_, index) => `c${index + 1}`), + positions: null, + xKind: 'category', + stacked: false, + horizontal: false, + notes: [], + ...over, + }; +} + +/** The box a path covers: the least and the most of its x and y. */ +function box(path: string) { + const numbers = [...path.matchAll(/(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)/g)]; + const xs = numbers.map((match) => Number(match[1])); + const ys = numbers.map((match) => Number(match[2])); + return { + left: Math.min(...xs), + right: Math.max(...xs), + top: Math.min(...ys), + bottom: Math.max(...ys), + }; +} + +describe('barPath', () => { + it('rounds the end away from the baseline and leaves the other square', () => { + const up = barPath(10, 20, 16, 100, 'top'); + expect(up.startsWith('M10,120L10,24Q10,20 14,20')).toBe(true); + expect(up.endsWith('L26,120Z')).toBe(true); + const across = barPath(0, 0, 100, 16, 'right'); + expect(across.startsWith('M0,0L96,0Q100,0 100,4')).toBe(true); + }); + + it('never rounds more than the bar is long or half as thick', () => { + // Two pixels of bar cannot carry a four pixel corner. + expect(barPath(0, 0, 16, 2, 'top')).toContain('Q0,0 2,0'); + expect(barPath(0, 0, 4, 50, 'top')).toContain('Q0,0 2,0'); + }); +}); + +describe('bars that stand up', () => { + const layout = layoutCartesian( + model({ series: [{ name: 'n', values: [10, 40, 0, null] }] }), + 600, + UNTITLED, + ); + + it('fit the frame, with room for the axes', () => { + const { frame } = layout; + expect(frame.width).toBe(600); + expect(frame.height).toBe(CHART_HEIGHT); + expect(frame.left + frame.plotWidth).toBeLessThanOrEqual(600); + expect(frame.top + frame.plotHeight).toBeLessThan(CHART_HEIGHT); + expect(layout.horizontal).toBe(false); + }); + + it('grow from the baseline, in proportion to their values', () => { + // No bar for a gap in the data. + expect(layout.bars.map((bar) => bar.index)).toEqual([0, 1, 2]); + const [small, large] = layout.bars.map((bar) => box(bar.path)); + if (!small || !large) { + throw new Error('Two bars were expected.'); + } + expect(small.bottom).toBeCloseTo(layout.zero, 1); + expect(large.bottom).toBeCloseTo(layout.zero, 1); + expect((large.bottom - large.top) / (small.bottom - small.top)).toBeCloseTo(4, 1); + }); + + it('are never thicker than 24 pixels, however much room there is', () => { + for (const bar of layout.bars) { + const { left, right } = box(bar.path); + expect(right - left).toBeLessThanOrEqual(24.01); + } + }); + + it('have an axis of round values that covers them', () => { + expect(layout.valueTicks.map((tick) => tick.label)).toEqual(['0', '10', '20', '30', '40']); + // More is higher up, which is a smaller y. + expect(layout.valueTicks[4]?.at).toBeLessThan(layout.valueTicks[0]?.at ?? 0); + expect(layout.zero).toBeCloseTo(layout.valueTicks[0]?.at ?? -1, 5); + }); + + it('name every position when the names fit', () => { + expect(layout.bandTicks.map((tick) => tick.label)).toEqual(['c1', 'c2', 'c3', 'c4']); + }); + + it('cut long names short before leaving any position unnamed', () => { + const names = [ + 'stackql', + 'stackql-provider-registry', + 'psql-wire', + 'stackql-actions-demo', + 'pystackql', + 'stackql-middleware', + 'stackql-jupyter-demo', + 'stackql-registry-docs', + ]; + const named = layoutCartesian( + model({ labels: names, series: [{ name: 'stars', values: names.map((_, index) => index) }] }), + 800, + UNTITLED, + ); + expect(named.bandTicks).toHaveLength(names.length); + expect(named.bandTicks[0]?.label).toBe('stackql'); + expect(named.bandTicks[1]?.label).toMatch(/^stackql-pr.*\.\.\.$/); + // No name is wider than the room under its bar. + for (const tick of named.bandTicks) { + expect(tick.label.length * 6.2).toBeLessThanOrEqual(named.band); + } + }); + + it('name every few positions when they do not', () => { + const many = Array.from({ length: 60 }, (_, index) => index); + const crowded = layoutCartesian( + model({ + labels: many.map((index) => `2026-11-${String(index).padStart(2, '0')}`), + series: [{ name: 'n', values: many }], + }), + 600, + UNTITLED, + ); + expect(crowded.bandTicks.length).toBeLessThan(20); + expect(crowded.bandTicks[0]?.label).toBe('2026-11-00'); + // Labels are far enough apart to be read. + const [first, second] = crowded.bandTicks; + expect((second?.at ?? 0) - (first?.at ?? 0)).toBeGreaterThan(60); + }); +}); + +describe('bars side by side and stacked', () => { + const series = [ + { name: 'open', values: [10, 5] }, + { name: 'closed', values: [20, -5] }, + ]; + + it('are kept apart by a gap, not by an outline', () => { + const layout = layoutCartesian(model({ series }), 600, UNTITLED); + const first = layout.bars.find((bar) => bar.series === 0 && bar.index === 0); + const second = layout.bars.find((bar) => bar.series === 1 && bar.index === 0); + if (!first || !second) { + throw new Error('Two bars were expected.'); + } + expect(box(second.path).left - box(first.path).right).toBeCloseTo(2, 1); + }); + + it('stack above zero and below it apart, with a gap between segments', () => { + const layout = layoutCartesian(model({ series, stacked: true }), 600, UNTITLED); + const at = (seriesIndex: number, index: number) => { + const bar = layout.bars.find((b) => b.series === seriesIndex && b.index === index); + if (!bar) { + throw new Error('A bar is missing.'); + } + return box(bar.path); + }; + // The second segment sits on the first, two pixels clear of it. + expect(at(0, 0).bottom).toBeCloseTo(layout.zero, 1); + expect(at(0, 0).top - at(1, 0).bottom).toBeCloseTo(2, 1); + // A value below zero hangs from the baseline. + expect(at(1, 1).top).toBeCloseTo(layout.zero, 1); + expect(at(0, 1).bottom).toBeCloseTo(layout.zero, 1); + // The axis covers the stack, not only the largest value. + expect(layout.valueTicks[layout.valueTicks.length - 1]?.label).toBe('30'); + }); +}); + +describe('bars that lie down', () => { + const layout = layoutCartesian( + model({ + labels: ['a-long-bucket-name', 'b', 'c'], + series: [{ name: 'size', values: [300, 150, 50] }], + horizontal: true, + }), + 600, + UNTITLED, + ); + + it('grow to the right from the baseline', () => { + const [longest, shorter] = layout.bars.map((bar) => box(bar.path)); + if (!longest || !shorter) { + throw new Error('Bars were expected.'); + } + expect(layout.horizontal).toBe(true); + expect(longest.left).toBeCloseTo(layout.zero, 1); + expect((longest.right - longest.left) / (shorter.right - shorter.left)).toBeCloseTo(2, 1); + }); + + it('are as tall as their rows need, and leave room for the names', () => { + expect(layout.frame.height).toBeLessThan(CHART_HEIGHT); + expect(layout.frame.left).toBeGreaterThan('a-long-bucket-name'.length * 6); + expect(layout.bandTicks.map((tick) => tick.label)).toEqual(['a-long-bucket-name', 'b', 'c']); + // One below the other. + expect(layout.centres[1]).toBeGreaterThan(layout.centres[0] ?? 0); + }); +}); + +describe('lines', () => { + const months = [Date.UTC(2023, 0, 1), Date.UTC(2023, 9, 1), Date.UTC(2026, 9, 1)]; + const line = model({ + type: 'line', + labels: ['2023-01', '2023-10', '2026-10'], + positions: months, + xKind: 'time', + series: [{ name: 'n', values: [1, 46, 13] }], + }); + const layout = layoutCartesian(line, 700, UNTITLED); + + it('place a date where it falls in time, not one step after the last', () => { + const [first, second, third] = layout.centres; + if (first === undefined || second === undefined || third === undefined) { + throw new Error('Three positions were expected.'); + } + // Nine months, then three years. + expect((third - second) / (second - first)).toBeCloseTo(4, 0); + expect(layout.band).toBe(0); + expect(layout.bandTicks.map((tick) => tick.label)).toEqual(['2023', '2024', '2025', '2026']); + }); + + it('draw one path through the points, and no wash under it', () => { + const [mark] = layout.lines; + expect(mark?.path.startsWith('M')).toBe(true); + expect(mark?.path.match(/L/g)).toHaveLength(2); + expect(mark?.area).toBeNull(); + expect(mark?.points.map((point) => point.value)).toEqual([1, 46, 13]); + expect(layout.bars).toEqual([]); + }); + + it('break the line at a gap in the data', () => { + const gapped = layoutCartesian( + model({ type: 'line', series: [{ name: 'n', values: [1, null, 3, 4] }] }), + 600, + UNTITLED, + ); + expect(gapped.lines[0]?.path.match(/M/g)).toHaveLength(2); + expect(gapped.lines[0]?.points).toHaveLength(3); + }); + + it('close an area down to the baseline', () => { + const area = layoutCartesian({ ...line, type: 'area' }, 700, UNTITLED); + expect(area.lines[0]?.area?.endsWith('Z')).toBe(true); + expect(area.lines[0]?.area).toContain(`,${Number(area.zero.toFixed(2))}Z`); + }); + + it('draw loose points with no line between them', () => { + const scatter = layoutCartesian( + model({ + type: 'scatter', + positions: [2, 8], + xKind: 'number', + series: [{ name: 'cost', values: [0.1, 0.4] }], + }), + 600, + UNTITLED, + ); + expect(scatter.lines[0]?.path).toBe(''); + expect(scatter.lines[0]?.points).toHaveLength(2); + expect(scatter.bandTicks.map((tick) => tick.label)).toEqual([ + '2', + '3', + '4', + '5', + '6', + '7', + '8', + ]); + // The ends of the axis are the least and the most of the data. + expect(scatter.bandTicks[0]?.at).toBeCloseTo(scatter.centres[0] ?? -1, 5); + expect(scatter.bandTicks[6]?.at).toBeCloseTo(scatter.centres[1] ?? -1, 5); + }); + + it('still draw one point alone', () => { + const one = layoutCartesian( + model({ + type: 'line', + labels: ['2026-11'], + positions: [Date.UTC(2026, 10, 1)], + xKind: 'time', + series: [{ name: 'n', values: [8] }], + }), + 600, + UNTITLED, + ); + const { frame } = one; + expect(one.centres[0]).toBeCloseTo(frame.left + frame.plotWidth / 2, 5); + expect(one.bandTicks).toHaveLength(1); + expect(one.lines[0]?.points).toHaveLength(1); + }); +}); + +describe('axis titles', () => { + it('take room from the plot', () => { + const bars = model({ series: [{ name: 'n', values: [1, 2] }] }); + const plain = layoutCartesian(bars, 600, UNTITLED); + const titled = layoutCartesian(bars, 600, { x: true, y: true }); + expect(titled.frame.left).toBeGreaterThan(plain.frame.left); + expect(titled.frame.plotHeight).toBeLessThan(plain.frame.plotHeight); + }); +}); + +describe('finding what is under the pointer', () => { + const layout = layoutCartesian( + model({ type: 'line', series: [{ name: 'n', values: [1, 2, 3] }] }), + 600, + UNTITLED, + ); + + it('takes the nearest position along the axis', () => { + expect(nearestPosition(layout, layout.centres[0] ?? 0)).toBe(0); + expect(nearestPosition(layout, (layout.centres[2] ?? 0) + 500)).toBe(2); + expect( + nearestPosition(layout, ((layout.centres[0] ?? 0) + (layout.centres[1] ?? 0)) / 2 + 1), + ).toBe(1); + expect(nearestPosition({ ...layout, centres: [] }, 10)).toBeNull(); + }); + + it('takes the nearest point, wherever in the plot the pointer is', () => { + const target = layout.lines[0]?.points[1]; + const hit = nearestPoint(layout, (target?.x ?? 0) + 3, (target?.y ?? 0) - 3); + expect(hit?.series).toBe(0); + expect(hit?.point.index).toBe(1); + expect(nearestPoint({ ...layout, lines: [] }, 0, 0)).toBeNull(); + }); +}); + +describe('layoutPie', () => { + const pie: PieModel = { + kind: 'pie', + slices: [ + { name: 'open', value: 100 }, + { name: 'closed', value: 300 }, + ], + total: 400, + valueName: 'n', + notes: [], + }; + + it('gives each part its share of the ring', () => { + const layout = layoutPie(pie, 200); + expect(layout.size).toBe(200); + expect(layout.slices.map((slice) => slice.share)).toEqual([0.25, 0.75]); + // The first part starts at the top, in the middle of the box. + expect(layout.slices[0]?.path.startsWith('M100,2A')).toBe(true); + // More than half the ring is the long way round. + expect(layout.slices[0]?.path).toContain(' 0 0 1 '); + expect(layout.slices[1]?.path).toContain(' 0 1 1 '); + }); + + it('draws a part that is the whole ring', () => { + const whole = layoutPie({ ...pie, slices: [{ name: 'all', value: 5 }], total: 5 }); + expect(whole.slices).toHaveLength(1); + expect(whole.slices[0]?.share).toBe(1); + // Two halves, since an arc cannot end where it starts. + expect(whole.slices[0]?.path.match(/Z/g)).toHaveLength(2); + }); +}); + +describe('formatShare', () => { + it('keeps a decimal only where it says something', () => { + expect(formatShare(0.25)).toBe('25%'); + expect(formatShare(0.0244)).toBe('2.4%'); + expect(formatShare(1)).toBe('100%'); + expect(formatShare(0)).toBe('0%'); + }); +}); diff --git a/src/lib/chartLayout.ts b/src/lib/chartLayout.ts new file mode 100644 index 0000000..225c4f1 --- /dev/null +++ b/src/lib/chartLayout.ts @@ -0,0 +1,500 @@ +// Where the marks of a chart go, in pixels. Pure functions: a model and a +// width in, positions and paths out. The components draw what this returns +// and work nothing out themselves. +// +// The marks follow a few fixed rules. A bar is at most 24 pixels thick, is +// square where it meets the baseline and rounded at its other end, and +// bars that touch are kept apart by a gap in the surface colour, never by +// an outline. Every chart has one value axis. + +import { + clip, + formatTick, + niceTicks, + timeTicks, + valueRange, + type CartesianModel, + type PieModel, +} from './chart'; + +/** The width of one character of an axis label, near enough to place labels by. */ +export const CHAR_WIDTH = 6.2; +/** The height of a chart whose bars stand up, or that is drawn with lines. */ +export const CHART_HEIGHT = 260; + +const MAX_BAR = 24; +const BAR_GAP = 2; +const BAR_RADIUS = 4; +/** The most characters of a name under a position, and the fewest worth showing. */ +const MAX_LABEL = 16; +const MIN_LABEL = 7; + +export interface Frame { + width: number; + height: number; + /** The plot area, inside the room left for the axes. */ + left: number; + top: number; + plotWidth: number; + plotHeight: number; +} + +export interface AxisTick { + /** Where the tick is along its axis, in pixels. */ + at: number; + label: string; +} + +export interface BarMark { + series: number; + index: number; + value: number; + path: string; +} + +export interface PointMark { + index: number; + x: number; + y: number; + value: number; +} + +export interface LineMark { + series: number; + /** The line itself. Empty for a scatter chart. */ + path: string; + /** The wash under the line, for an area chart. */ + area: string | null; + points: PointMark[]; +} + +export interface CartesianLayout { + frame: Frame; + /** The bars lie down, so the value axis runs across. */ + horizontal: boolean; + valueTicks: AxisTick[]; + bandTicks: AxisTick[]; + /** Where the value zero is, or the end of the axis nearest to it. */ + zero: number; + /** The middle of each position along the band axis. */ + centres: number[]; + /** The room each position has along the band axis. Zero on a continuous axis. */ + band: number; + bars: BarMark[]; + lines: LineMark[]; +} + +type Side = 'top' | 'bottom' | 'left' | 'right'; + +const n = (value: number) => Number(value.toFixed(2)); + +/** A bar as a path, with the end that is away from the baseline rounded. */ +export function barPath(x: number, y: number, width: number, height: number, round: Side): string { + const w = Math.max(0, width); + const h = Math.max(0, height); + const across = round === 'top' || round === 'bottom' ? w : h; + const along = round === 'top' || round === 'bottom' ? h : w; + const r = Math.max(0, Math.min(BAR_RADIUS, across / 2, along)); + const [x0, y0, x1, y1] = [n(x), n(y), n(x + w), n(y + h)]; + switch (round) { + case 'top': + return `M${x0},${y1}L${x0},${n(y + r)}Q${x0},${y0} ${n(x + r)},${y0}L${n(x + w - r)},${y0}Q${x1},${y0} ${x1},${n(y + r)}L${x1},${y1}Z`; + case 'bottom': + return `M${x0},${y0}L${x0},${n(y + h - r)}Q${x0},${y1} ${n(x + r)},${y1}L${n(x + w - r)},${y1}Q${x1},${y1} ${x1},${n(y + h - r)}L${x1},${y0}Z`; + case 'right': + return `M${x0},${y0}L${n(x + w - r)},${y0}Q${x1},${y0} ${x1},${n(y + r)}L${x1},${n(y + h - r)}Q${x1},${y1} ${n(x + w - r)},${y1}L${x0},${y1}Z`; + case 'left': + return `M${x1},${y0}L${n(x + r)},${y0}Q${x0},${y0} ${x0},${n(y + r)}L${x0},${n(y + h - r)}Q${x0},${y1} ${n(x + r)},${y1}L${x1},${y1}Z`; + } +} + +/** A bar with no free end: a segment inside a stack. */ +function rectPath(x: number, y: number, width: number, height: number): string { + const [x0, y0] = [n(x), n(y)]; + const [x1, y1] = [n(x + Math.max(0, width)), n(y + Math.max(0, height))]; + return `M${x0},${y0}L${x1},${y0}L${x1},${y1}L${x0},${y1}Z`; +} + +interface ValueAxis { + ticks: number[]; + min: number; + max: number; + labels: string[]; +} + +function valueAxis(model: CartesianModel, target: number): ValueAxis { + const [low, high] = valueRange(model); + const ticks = niceTicks(low, high, target); + return { + ticks, + min: ticks[0] ?? 0, + max: ticks[ticks.length - 1] ?? 1, + labels: ticks.map((tick) => formatTick(tick, ticks)), + }; +} + +const longest = (labels: string[], cap: number) => + Math.min( + cap, + labels.reduce((most, label) => Math.max(most, label.length), 1), + ); + +/** + * The bars of one position. `along` turns a value into a place on the + * value axis, and `place` turns a bar's box, given along the band axis and + * the value axis, into a path. + */ +function barsAt( + model: CartesianModel, + index: number, + start: number, + thickness: number, + along: (value: number) => number, + place: ( + band: number, + thick: number, + from: number, + to: number, + value: number, + outer: boolean, + ) => string, +): BarMark[] { + const marks: BarMark[] = []; + if (model.stacked) { + let up = 0; + let down = 0; + // The last segment on each side of zero is the one with the free end. + let lastUp = -1; + let lastDown = -1; + model.series.forEach((entry, series) => { + const value = entry.values[index] ?? 0; + if (value > 0) { + lastUp = series; + } else if (value < 0) { + lastDown = series; + } + }); + model.series.forEach((entry, series) => { + const value = entry.values[index]; + if (value === null || value === undefined || value === 0) { + return; + } + const base = value > 0 ? up : down; + if (value > 0) { + up += value; + } else { + down += value; + } + let from = along(base); + const to = along(base + value); + // A gap in the surface colour between one segment and the next. + if (base !== 0 && Math.abs(to - from) > BAR_GAP + 1) { + from += Math.sign(to - from) * BAR_GAP; + } + const outer = series === (value > 0 ? lastUp : lastDown); + marks.push({ series, index, value, path: place(start, thickness, from, to, value, outer) }); + }); + return marks; + } + model.series.forEach((entry, series) => { + const value = entry.values[index]; + if (value === null || value === undefined) { + return; + } + const at = start + series * (thickness + BAR_GAP); + marks.push({ + series, + index, + value, + path: place(at, thickness, along(0), along(value), value, true), + }); + }); + return marks; +} + +function layoutVertical(model: CartesianModel, width: number, titled: Titled): CartesianLayout { + const count = model.labels.length; + const axis = valueAxis(model, 5); + const left = Math.ceil(longest(axis.labels, 12) * CHAR_WIDTH) + 12 + (titled.y ? 18 : 0); + const top = 10; + const bottom = 24 + (titled.x ? 18 : 0); + const plotWidth = Math.max(60, width - left - 14); + const plotHeight = CHART_HEIGHT - top - bottom; + const span = axis.max - axis.min || 1; + const clamp = (value: number) => Math.min(Math.max(value, axis.min), axis.max); + const y = (value: number) => top + plotHeight - ((clamp(value) - axis.min) / span) * plotHeight; + const frame: Frame = { width, height: CHART_HEIGHT, left, top, plotWidth, plotHeight }; + + let centres: number[]; + let bandTicks: AxisTick[]; + let band = plotWidth / Math.max(1, count); + if (model.positions) { + const positions = model.positions; + const first = positions[0] ?? 0; + const last = positions[positions.length - 1] ?? first; + const pad = 10; + const x = (position: number) => + last === first + ? left + plotWidth / 2 + : left + pad + ((position - first) / (last - first)) * (plotWidth - 2 * pad); + centres = positions.map(x); + band = 0; + if (model.xKind === 'time') { + bandTicks = timeTicks(first, last, Math.max(2, Math.floor(plotWidth / 90))).map((tick) => ({ + at: x(tick.value), + label: tick.label, + })); + } else { + const ticks = niceTicks(first, last, Math.max(2, Math.floor(plotWidth / 80))).filter( + (tick) => tick >= first && tick <= last, + ); + bandTicks = ticks.map((tick) => ({ at: x(tick), label: formatTick(tick, ticks) })); + } + if (bandTicks.length === 0) { + // Too short a span for a round tick: name the ends. + const ends = count > 1 ? [0, count - 1] : [0]; + bandTicks = ends.map((index) => ({ + at: centres[index] ?? left, + label: clip(model.labels[index] ?? '', 16), + })); + } + } else { + centres = model.labels.map((_, index) => left + band * (index + 0.5)); + // Every position is named when its name fits under it, cut short if it + // has to be, as long as enough of it is left to tell the names apart. + // Otherwise every few are named, and the rest are read from the tooltip + // or the table. + const widest = longest(model.labels, MAX_LABEL); + const fits = Math.floor((band - 8) / CHAR_WIDTH); + if (fits >= Math.min(widest, MIN_LABEL)) { + bandTicks = model.labels.map((label, index) => ({ + at: centres[index] ?? left, + label: clip(label, Math.min(MAX_LABEL, fits)), + })); + } else { + const every = Math.max(1, Math.ceil((widest * CHAR_WIDTH + 12) / band)); + bandTicks = model.labels.flatMap((label, index) => + index % every === 0 ? [{ at: centres[index] ?? left, label: clip(label, MAX_LABEL) }] : [], + ); + } + } + + const bars: BarMark[] = []; + const lines: LineMark[] = []; + if (model.type === 'bar') { + const groups = model.stacked ? 1 : model.series.length; + const thickness = Math.max( + 1, + Math.min(MAX_BAR, (band * 0.72 - (groups - 1) * BAR_GAP) / groups), + ); + const groupWidth = groups * thickness + (groups - 1) * BAR_GAP; + for (let index = 0; index < count; index += 1) { + const start = (centres[index] ?? left) - groupWidth / 2; + bars.push( + ...barsAt(model, index, start, thickness, y, (at, thick, from, to, value, outer) => { + // At least a pixel, so that a small value is still a mark. + const height = Math.max(1, Math.abs(to - from)); + const topEdge = value >= 0 ? from - height : from; + return outer + ? barPath(at, topEdge, thick, height, value >= 0 ? 'top' : 'bottom') + : rectPath(at, topEdge, thick, height); + }), + ); + } + } else { + const zero = y(0); + model.series.forEach((entry, series) => { + const points: PointMark[] = []; + let path = ''; + let area = ''; + let run: PointMark[] = []; + const endRun = () => { + const [start] = run; + const end = run[run.length - 1]; + if (start && end && model.type === 'area') { + area += `M${n(start.x)},${n(zero)}${run.map((p) => `L${n(p.x)},${n(p.y)}`).join('')}L${n(end.x)},${n(zero)}Z`; + } + run = []; + }; + entry.values.forEach((value, index) => { + if (value === null) { + endRun(); + return; + } + const point = { index, x: centres[index] ?? left, y: y(value), value }; + path += `${run.length === 0 ? 'M' : 'L'}${n(point.x)},${n(point.y)}`; + run.push(point); + points.push(point); + }); + endRun(); + lines.push({ + series, + path: model.type === 'scatter' ? '' : path, + area: model.type === 'area' ? area : null, + points, + }); + }); + } + + return { + frame, + horizontal: false, + valueTicks: axis.ticks.map((tick, index) => ({ at: y(tick), label: axis.labels[index] ?? '' })), + bandTicks, + zero: y(0), + centres, + band, + bars, + lines, + }; +} + +function layoutHorizontal(model: CartesianModel, width: number, titled: Titled): CartesianLayout { + const count = model.labels.length; + const groups = model.stacked ? 1 : model.series.length; + const thickness = groups === 1 ? 16 : 10; + const groupHeight = groups * thickness + (groups - 1) * BAR_GAP; + const band = Math.max(24, groupHeight + 10); + const left = Math.ceil(longest(model.labels, 28) * CHAR_WIDTH) + 12 + (titled.x ? 18 : 0); + const top = 6; + const bottom = 24 + (titled.y ? 18 : 0); + const plotWidth = Math.max(60, width - left - 22); + const plotHeight = count * band; + const axis = valueAxis(model, Math.max(2, Math.floor(plotWidth / 90))); + const span = axis.max - axis.min || 1; + const clamp = (value: number) => Math.min(Math.max(value, axis.min), axis.max); + const x = (value: number) => left + ((clamp(value) - axis.min) / span) * plotWidth; + const centres = model.labels.map((_, index) => top + band * (index + 0.5)); + + const bars: BarMark[] = []; + for (let index = 0; index < count; index += 1) { + const start = (centres[index] ?? top) - groupHeight / 2; + bars.push( + ...barsAt(model, index, start, thickness, x, (at, thick, from, to, value, outer) => { + const length = Math.max(1, Math.abs(to - from)); + const leftEdge = value >= 0 ? from : from - length; + return outer + ? barPath(leftEdge, at, length, thick, value >= 0 ? 'right' : 'left') + : rectPath(leftEdge, at, length, thick); + }), + ); + } + + return { + frame: { width, height: top + plotHeight + bottom, left, top, plotWidth, plotHeight }, + horizontal: true, + valueTicks: axis.ticks.map((tick, index) => ({ at: x(tick), label: axis.labels[index] ?? '' })), + bandTicks: model.labels.map((label, index) => ({ + at: centres[index] ?? top, + label: clip(label, 28), + })), + zero: x(0), + centres, + band, + bars, + lines: [], + }; +} + +interface Titled { + /** The axis along the bottom has a title. */ + x: boolean; + /** The axis up the side has a title. */ + y: boolean; +} + +/** Lays out a chart with axes at the width it will be drawn at. */ +export function layoutCartesian( + model: CartesianModel, + width: number, + titled: Titled, +): CartesianLayout { + return model.horizontal + ? layoutHorizontal(model, width, titled) + : layoutVertical(model, width, titled); +} + +/** The position nearest to a place along the band axis. */ +export function nearestPosition(layout: CartesianLayout, at: number): number | null { + let best: number | null = null; + let distance = Infinity; + layout.centres.forEach((centre, index) => { + const away = Math.abs(centre - at); + if (away < distance) { + distance = away; + best = index; + } + }); + return best; +} + +/** The point nearest to a place in the plot, for a chart of loose points. */ +export function nearestPoint( + layout: CartesianLayout, + x: number, + y: number, +): { series: number; point: PointMark } | null { + let best: { series: number; point: PointMark } | null = null; + let distance = Infinity; + for (const line of layout.lines) { + for (const point of line.points) { + const away = (point.x - x) ** 2 + (point.y - y) ** 2; + if (away < distance) { + distance = away; + best = { series: line.series, point }; + } + } + } + return best; +} + +export interface SliceMark { + index: number; + name: string; + value: number; + /** The share of the whole, from 0 to 1. */ + share: number; + path: string; +} + +export interface PieLayout { + size: number; + slices: SliceMark[]; +} + +/** + * A ring cut into parts, starting at the top and going clockwise. A part + * that is the whole ring is drawn as two halves, since an arc cannot end + * where it starts. + */ +export function layoutPie(model: PieModel, size = 180): PieLayout { + const centre = size / 2; + const outer = size / 2 - 2; + const inner = outer * 0.6; + const point = (radius: number, turn: number) => { + const angle = turn * 2 * Math.PI - Math.PI / 2; + return `${n(centre + radius * Math.cos(angle))},${n(centre + radius * Math.sin(angle))}`; + }; + const arc = (from: number, to: number) => { + const large = to - from > 0.5 ? 1 : 0; + return ( + `M${point(outer, from)}A${outer},${outer} 0 ${large} 1 ${point(outer, to)}` + + `L${point(inner, to)}A${inner},${inner} 0 ${large} 0 ${point(inner, from)}Z` + ); + }; + let turned = 0; + const slices = model.slices.map((slice, index) => { + const share = model.total > 0 ? slice.value / model.total : 0; + const from = turned; + turned += share; + const path = share >= 0.9999 ? `${arc(0, 0.5)}${arc(0.5, 1)}` : arc(from, Math.min(1, turned)); + return { index, name: slice.name, value: slice.value, share, path }; + }); + return { size, slices }; +} + +/** A share as a percentage, for example 24% or 2.4%. */ +export function formatShare(share: number): string { + const percent = share * 100; + return `${percent >= 10 || percent === 0 ? percent.toFixed(0) : percent.toFixed(1)}%`; +} diff --git a/src/lib/chat.test.ts b/src/lib/chat.test.ts new file mode 100644 index 0000000..58b75fd --- /dev/null +++ b/src/lib/chat.test.ts @@ -0,0 +1,559 @@ +import { describe, expect, it } from 'vitest'; +import type { AgentEvent, ApprovalRequest, TurnSummary } from '../host/types'; +import { + applyAgentEvent, + approvalAnswered, + argumentSummary, + chatProgress, + chatTitle, + emptyChat, + looksLikeSql, + modeDescription, + pendingApprovals, + splitFences, + toolTitle, + turnFailed, + turnFinished, + userSent, + type ChatState, + type ToolItem, +} from './chat'; + +const DELETE_SQL = "DELETE FROM github.repos.repos WHERE owner = 'x' AND repo = 'y'"; + +const request: ApprovalRequest = { + id: 'approval-1', + message: `Approve run_mutation_query (mutation_delete)?\n\nSQL: ${DELETE_SQL}`, + tool: 'run_mutation_query', + queryClass: 'mutation_delete', + sql: DELETE_SQL, +}; + +const summary = (over: Partial = {}): TurnSummary => ({ + steps: 2, + toolCalls: 1, + stopped: false, + stop: { kind: 'endTurn' }, + // A provider that reports no counts, unless a test says otherwise. + usage: { inputTokens: null, outputTokens: null, cachedInputTokens: null }, + ...over, +}); + +function play(events: AgentEvent[], from: ChatState = userSent(emptyChat, 'hello')): ChatState { + return events.reduce(applyAgentEvent, from); +} + +const started = (id: string, tool: string, sql: string | null): AgentEvent => ({ + event: 'toolCallStarted', + data: { id, tool, arguments: sql ? { sql } : {}, sql, step: 1 }, +}); + +const finished = (id: string, isError = false, text = 'ok'): AgentEvent => ({ + event: 'toolCallFinished', + data: { id, isError, text, table: null, engineNotes: [], elapsedMs: 12 }, +}); + +function tools(state: ChatState): ToolItem[] { + return state.items.filter((item): item is ToolItem => item.kind === 'tool'); +} + +describe('a turn', () => { + it('starts busy with the operator message', () => { + const state = userSent(emptyChat, 'what is installed?'); + expect(state.busy).toBe(true); + expect(state.items).toEqual([{ kind: 'user', key: 'item-0', text: 'what is installed?' }]); + }); + + it('shows a tool call with its SQL, then its result', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT 1'), + { + event: 'toolCallFinished', + data: { + id: 'c1', + isError: false, + text: '| one |', + table: { columns: ['one'], rows: [['1']], totalRows: 1, truncated: false }, + engineNotes: [], + elapsedMs: 30, + }, + }, + { event: 'assistantText', data: { text: 'It is 1.' } }, + ]); + const [tool] = tools(state); + expect(tool).toMatchObject({ + tool: 'run_select_query', + sql: 'SELECT 1', + status: 'done', + elapsedMs: 30, + }); + expect(tool?.table?.rows).toEqual([['1']]); + expect(state.items.at(-1)).toMatchObject({ kind: 'assistant', text: 'It is 1.' }); + }); + + it('gives every item a distinct key', () => { + const state = play([ + { event: 'sessionStarted', data: { mode: 'safe', protocolVersion: '2025-11-25', tools: 15 } }, + started('c1', 'list_providers', null), + finished('c1'), + { event: 'assistantText', data: { text: 'done' } }, + ]); + const keys = state.items.map((item) => item.key); + expect(new Set(keys).size).toBe(keys.length); + }); + + it('marks a failed tool call and keeps engine notes', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT x'), + { + event: 'toolCallFinished', + data: { + id: 'c1', + isError: false, + text: '**no results**', + table: { columns: [], rows: [], totalRows: 0, truncated: false }, + engineNotes: ['http response status code: 404'], + elapsedMs: 900, + }, + }, + started('c2', 'list_services', null), + finished('c2', true, 'no provider document'), + ]); + const [first, second] = tools(state); + expect(first?.engineNotes).toEqual(['http response status code: 404']); + expect(second).toMatchObject({ status: 'error', text: 'no provider document' }); + }); +}); + +describe('approval', () => { + const asked = play([ + started('c1', 'run_mutation_query', DELETE_SQL), + { event: 'approvalRequested', data: { request } }, + ]); + + it('attaches the prompt to the tool call that is waiting on it', () => { + const [tool] = tools(asked); + expect(tool?.approval).toEqual({ request, decision: 'pending' }); + expect(tool?.status).toBe('running'); + expect(pendingApprovals(asked)).toEqual([request]); + }); + + it('records the operator answer and stops listing the prompt as pending', () => { + const answered = approvalAnswered(asked, 'approval-1', 'decline'); + expect(tools(answered)[0]?.approval?.decision).toBe('decline'); + expect(pendingApprovals(answered)).toEqual([]); + }); + + it('does not change an answer once given', () => { + const declined = approvalAnswered(asked, 'approval-1', 'decline'); + const again = approvalAnswered(declined, 'approval-1', 'accept'); + expect(tools(again)[0]?.approval?.decision).toBe('decline'); + }); + + it('ignores an answer for an unknown prompt', () => { + expect(approvalAnswered(asked, 'approval-99', 'accept')).toEqual(asked); + }); + + it('treats a prompt still open when the call ends as dismissed', () => { + const ended = applyAgentEvent(asked, finished('c1', true, 'approval prompt was dismissed')); + expect(tools(ended)[0]?.approval?.decision).toBe('cancel'); + expect(pendingApprovals(ended)).toEqual([]); + }); + + it('never loses a prompt that arrives with no tool call running', () => { + const state = play([{ event: 'approvalRequested', data: { request } }]); + expect(pendingApprovals(state)).toEqual([request]); + expect(tools(state)[0]?.sql).toBe(DELETE_SQL); + }); + + it('attaches to the running call, not an earlier finished one', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT 1'), + finished('c1'), + started('c2', 'run_mutation_query', DELETE_SQL), + { event: 'approvalRequested', data: { request } }, + ]); + const [first, second] = tools(state); + expect(first?.approval).toBeNull(); + expect(second?.approval?.decision).toBe('pending'); + }); +}); + +describe('approval while several calls run', () => { + const OTHER_SQL = "DELETE FROM github.repos.repos WHERE owner = 'x' AND repo = 'z'"; + const ask = (id: string, sql: string): AgentEvent => ({ + event: 'approvalRequested', + data: { request: { ...request, id, sql, message: `Approve?\n\nSQL: ${sql}` } }, + }); + + it('goes to the call that sent the statement, not to the newest one', () => { + const state = play([ + started('c1', 'run_mutation_query', DELETE_SQL), + started('c2', 'run_mutation_query', OTHER_SQL), + started('c3', 'run_select_query', 'SELECT 1'), + ask('approval-1', DELETE_SQL), + ]); + const [first, second, third] = tools(state); + expect(first?.approval?.request.id).toBe('approval-1'); + expect(second?.approval).toBeNull(); + expect(third?.approval).toBeNull(); + }); + + it('gives two calls with the same statement a prompt each', () => { + const state = play([ + started('c1', 'run_mutation_query', DELETE_SQL), + started('c2', 'run_mutation_query', DELETE_SQL), + ask('approval-1', DELETE_SQL), + ask('approval-2', DELETE_SQL), + ]); + const [first, second] = tools(state); + expect(first?.approval?.request.id).toBe('approval-1'); + expect(second?.approval?.request.id).toBe('approval-2'); + expect(pendingApprovals(state)).toHaveLength(2); + }); + + it('answers each prompt on its own', () => { + let state = play([ + started('c1', 'run_mutation_query', DELETE_SQL), + started('c2', 'run_mutation_query', OTHER_SQL), + ask('approval-1', DELETE_SQL), + ask('approval-2', OTHER_SQL), + ]); + state = approvalAnswered(state, 'approval-2', 'decline'); + const [first, second] = tools(state); + expect(first?.approval?.decision).toBe('pending'); + expect(second?.approval?.decision).toBe('decline'); + }); + + it('falls back to the newest call still waiting when nothing matches', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT 1'), + started('c2', 'run_select_query', 'SELECT 2'), + ask('approval-1', 'SELECT something else'), + ]); + const [first, second] = tools(state); + expect(first?.approval).toBeNull(); + expect(second?.approval?.request.id).toBe('approval-1'); + }); +}); + +describe('the end of a turn', () => { + it('clears busy', () => { + const state = turnFinished(play([{ event: 'assistantText', data: { text: 'hi' } }]), summary()); + expect(state.busy).toBe(false); + expect(state.items.at(-1)).toMatchObject({ kind: 'assistant' }); + }); + + it('says so when the operator stopped it, and settles what was running', () => { + const state = turnFinished( + play([ + started('c1', 'run_mutation_query', DELETE_SQL), + { event: 'approvalRequested', data: { request } }, + ]), + summary({ stopped: true }), + ); + const [tool] = tools(state); + expect(tool?.status).toBe('error'); + expect(tool?.approval?.decision).toBe('cancel'); + expect(state.items.at(-1)).toMatchObject({ kind: 'notice', tone: 'warn' }); + expect(pendingApprovals(state)).toEqual([]); + }); + + it('reports a refusal and a cut-off reply', () => { + const refused = turnFinished( + userSent(emptyChat, 'x'), + summary({ stop: { kind: 'refused', detail: 'The model declined this request.' } }), + ); + expect(refused.items.at(-1)).toMatchObject({ + kind: 'notice', + text: 'The model declined this request.', + }); + + const cut = turnFinished(userSent(emptyChat, 'x'), summary({ stop: { kind: 'maxTokens' } })); + expect(cut.items.at(-1)).toMatchObject({ kind: 'notice', tone: 'warn' }); + }); + + it('shows a failure as an error and clears busy', () => { + const state = turnFailed(userSent(emptyChat, 'x'), { + kind: 'agent', + message: 'The inference provider rejected the API key.', + }); + expect(state.busy).toBe(false); + expect(state.items.at(-1)).toMatchObject({ + kind: 'notice', + tone: 'error', + text: 'The inference provider rejected the API key.', + }); + }); +}); + +describe('splitFences', () => { + it('returns plain text as one segment', () => { + expect(splitFences('Just words.')).toEqual([{ kind: 'text', text: 'Just words.' }]); + }); + + it('separates prose from fenced code', () => { + const segments = splitFences( + 'Here is the query:\n\n```sql\nSELECT name\nFROM github.repos.repos\n```\n\nIt lists repos.', + ); + expect(segments).toEqual([ + { kind: 'text', text: 'Here is the query:' }, + { kind: 'code', language: 'sql', code: 'SELECT name\nFROM github.repos.repos' }, + { kind: 'text', text: 'It lists repos.' }, + ]); + }); + + it('handles several blocks and a block with no language', () => { + const segments = splitFences('```\nSHOW PROVIDERS\n```\nthen\n```json\n{"a":1}\n```'); + expect(segments.map((s) => s.kind)).toEqual(['code', 'text', 'code']); + expect(segments[0]).toMatchObject({ language: '', code: 'SHOW PROVIDERS' }); + expect(segments[2]).toMatchObject({ language: 'json' }); + }); + + it('takes a fence that is not closed yet as a block still being written', () => { + expect(splitFences('```sql\nSELECT 1')).toEqual([ + { kind: 'code', language: 'sql', code: 'SELECT 1', open: true }, + ]); + // The pieces of a reply can stop anywhere, also half way through the fence line. + expect(splitFences('Here it is:\n\n```cha')).toEqual([ + { kind: 'text', text: 'Here it is:' }, + { kind: 'code', language: 'cha', code: '', open: true }, + ]); + expect(splitFences('```sql\nSELECT 1\n```\nand\n```chart\n{"type"')).toEqual([ + { kind: 'code', language: 'sql', code: 'SELECT 1' }, + { kind: 'text', text: 'and' }, + { kind: 'code', language: 'chart', code: '{"type"', open: true }, + ]); + }); + + it('leaves backticks in the middle of a line alone', () => { + expect(splitFences('Use ``` to open a block.')).toEqual([ + { kind: 'text', text: 'Use ``` to open a block.' }, + ]); + }); + + it('returns nothing for blank text', () => { + expect(splitFences(' \n ')).toEqual([]); + }); +}); + +describe('looksLikeSql', () => { + it('accepts sql fences and unlabelled statements', () => { + expect(looksLikeSql({ kind: 'code', language: 'sql', code: 'anything' })).toBe(true); + expect(looksLikeSql({ kind: 'code', language: '', code: ' select 1' })).toBe(true); + expect(looksLikeSql({ kind: 'code', language: '', code: 'REGISTRY PULL github' })).toBe(true); + }); + + it('rejects other code and prose', () => { + expect(looksLikeSql({ kind: 'code', language: 'json', code: '{"select": 1}' })).toBe(false); + expect(looksLikeSql({ kind: 'code', language: '', code: 'name | version' })).toBe(false); + expect(looksLikeSql({ kind: 'text', text: 'select 1' })).toBe(false); + }); +}); + +describe('labels', () => { + it('names known tools and falls back to the raw name', () => { + expect(toolTitle('run_mutation_query')).toBe('Run mutation'); + expect(toolTitle('something_new')).toBe('something_new'); + }); + + it('summarises arguments without repeating the SQL', () => { + expect(argumentSummary({ provider: 'github', service: 'repos' })).toBe( + 'provider: github, service: repos', + ); + expect(argumentSummary({ sql: 'SELECT 1', row_limit: 10 })).toBe('row_limit: 10'); + expect(argumentSummary({})).toBe(''); + expect(argumentSummary(null)).toBe(''); + }); +}); + +describe('a reply that arrives in pieces', () => { + const delta = (id: string, text: string): AgentEvent => ({ + event: 'assistantDelta', + data: { id, text }, + }); + + it('joins the pieces of one message into one item', () => { + const state = play([delta('m1', 'Let me '), delta('m1', 'check.')]); + const replies = state.items.filter((item) => item.kind === 'assistant'); + expect(replies).toHaveLength(1); + expect(replies[0]).toMatchObject({ text: 'Let me check.' }); + }); + + it('starts a new item for a new message', () => { + const state = play([delta('m1', 'First.'), delta('m2', 'Second.')]); + const texts = state.items.flatMap((item) => (item.kind === 'assistant' ? [item.text] : [])); + expect(texts).toEqual(['First.', 'Second.']); + }); + + it('finds its message past a tool call that started in between', () => { + const state = play([ + delta('m1', 'Running '), + started('c1', 'run_select_query', 'SELECT 1'), + delta('m1', 'it now.'), + finished('c1'), + delta('m2', 'Done.'), + ]); + expect(state.items.map((item) => item.kind)).toEqual([ + 'user', + 'assistant', + 'tool', + 'assistant', + ]); + expect(state.items[1]).toMatchObject({ text: 'Running it now.' }); + expect(state.items[3]).toMatchObject({ text: 'Done.' }); + }); + + it('keeps whole replies and pieces apart', () => { + const state = play([ + { event: 'assistantText', data: { text: 'Whole.' } }, + delta('m1', 'Piece.'), + ]); + const texts = state.items.flatMap((item) => (item.kind === 'assistant' ? [item.text] : [])); + expect(texts).toEqual(['Whole.', 'Piece.']); + }); + + it('moves the progress marker with every piece', () => { + const before = play([delta('m1', 'a')]); + const after = applyAgentEvent(before, delta('m1', 'b')); + expect(chatProgress(after)).toBeGreaterThan(chatProgress(before)); + expect(chatProgress(applyAgentEvent(after, delta('m2', 'c')))).toBeGreaterThan( + chatProgress(after), + ); + }); +}); + +describe('a delegated agent', () => { + it('shows what was started, in which mode and with which model', () => { + const state = play([ + { + event: 'delegateStarted', + data: { + mode: 'safe', + agent: 'GitHub Copilot CLI', + version: '1.0.113', + protocol: 'ACP 1', + model: 'small', + tools: 15, + }, + }, + ]); + expect(state.items[1]).toMatchObject({ + kind: 'session', + mode: 'safe', + tools: 15, + agent: 'GitHub Copilot CLI', + agentVersion: '1.0.113', + agentProtocol: 'ACP 1', + model: 'small', + }); + }); + + it('says changes are refused where another backend would ask', () => { + expect(modeDescription('safe', false)).toBe( + 'Queries run. Each change needs your approval before it runs.', + ); + expect(modeDescription('delete_safe', false)).toBe( + 'Queries and changes run. DELETE and EXEC need your approval.', + ); + // An API key backend can show the prompt, so nothing says it cannot. + for (const mode of ['read_only', 'safe', 'delete_safe', 'full_access'] as const) { + expect(modeDescription(mode, false)).not.toContain('cannot'); + } + // A delegated agent cannot, so a change is refused and the text says so. + expect(modeDescription('safe', true)).toContain('refused'); + expect(modeDescription('safe', true)).not.toContain('needs your approval'); + expect(modeDescription('delete_safe', true)).toContain('refused'); + // Where nothing needs approval the two read the same. + expect(modeDescription('read_only', true)).toBe(modeDescription('read_only', false)); + expect(modeDescription('full_access', true)).toBe(modeDescription('full_access', false)); + }); +}); + +describe('what a turn used', () => { + it('is kept when the turn ends, as the provider counted it', () => { + const usage = { inputTokens: 19353, outputTokens: 92, cachedInputTokens: 9533 }; + const state = turnFinished(play([]), summary({ usage })); + expect(state.items.at(-1)).toEqual({ kind: 'usage', key: 'item-1', usage }); + expect(state.busy).toBe(false); + }); + + it('is kept when only one of the two counts was reported', () => { + const usage = { inputTokens: null, outputTokens: 40, cachedInputTokens: null }; + const state = turnFinished(play([]), summary({ usage })); + expect(state.items.at(-1)).toMatchObject({ kind: 'usage', usage }); + }); + + it('is not made up when the provider reported nothing', () => { + const state = turnFinished(play([]), summary()); + expect(state.items.some((item) => item.kind === 'usage')).toBe(false); + }); + + it('comes before the notice that a turn was stopped', () => { + const usage = { inputTokens: 10, outputTokens: 2, cachedInputTokens: null }; + const state = turnFinished(play([]), summary({ stopped: true, usage })); + expect(state.items.slice(-2).map((item) => item.kind)).toEqual(['usage', 'notice']); + }); +}); + +describe('subagents', () => { + it('marks a call with the subagent that made it', () => { + const state = play([ + { + event: 'toolCallStarted', + data: { + id: 't1', + tool: 'subagent', + arguments: { task: 'Count github repos' }, + sql: null, + step: 2, + }, + }, + { + event: 'toolCallStarted', + data: { + id: 'q1', + tool: 'run_select_query', + arguments: { sql: 'SELECT 1' }, + sql: 'SELECT 1', + agent: 'github-count', + step: 2, + }, + }, + ]); + const [task, query] = tools(state); + expect(task).toMatchObject({ tool: 'subagent', agent: null, step: 2 }); + expect(query).toMatchObject({ tool: 'run_select_query', agent: 'github-count', step: 2 }); + expect(toolTitle('subagent')).toBe('Subagent'); + expect(argumentSummary(task?.arguments)).toBe('task: Count github repos'); + }); + + it('finishes a subagent and its calls each by their own id', () => { + const state = play([ + started('t1', 'subagent', null), + { ...started('q1', 'run_select_query', 'SELECT 1') }, + finished('q1'), + finished('t1', false, 'github has 90 repos.'), + ]); + const [task, query] = tools(state); + expect(query?.status).toBe('done'); + expect(task).toMatchObject({ status: 'done', text: 'github has 90 repos.' }); + }); +}); + +describe('chatTitle', () => { + it('is null before the first message', () => { + expect(chatTitle(emptyChat)).toBeNull(); + }); + + it('is the start of the first message, on one line', () => { + const state = userSent(userSent(emptyChat, 'How many\n buckets do I have?'), 'and regions?'); + expect(chatTitle(state)).toBe('How many buckets do I have?'); + }); + + it('is cut when long', () => { + const title = chatTitle(userSent(emptyChat, 'word '.repeat(40)), 20); + expect(title).toHaveLength(20); + expect(title?.endsWith('...')).toBe(true); + }); +}); diff --git a/src/lib/chat.ts b/src/lib/chat.ts new file mode 100644 index 0000000..2297468 --- /dev/null +++ b/src/lib/chat.ts @@ -0,0 +1,465 @@ +// The state of the chat pane, built from the events the host streams during +// a turn. Pure functions, so the mapping can be tested without a host. + +import type { + AgentEvent, + AgentTable, + ApprovalDecision, + ApprovalRequest, + HostError, + SafetyMode, + TokenUsage, + TurnSummary, +} from '../host/types'; + +export interface ApprovalState { + request: ApprovalRequest; + /** `pending` until the operator answers. */ + decision: 'pending' | ApprovalDecision; +} + +export interface ToolItem { + kind: 'tool'; + key: string; + callId: string; + tool: string; + /** The subagent that made the call. Null for the main agent. */ + agent: string | null; + /** + * Which of the model's steps in the turn asked for the call. Calls of one + * step were asked for together. Null for a call the host never announced. + */ + step: number | null; + /** The statement, when the tool takes one. Always shown as SQL. */ + sql: string | null; + arguments: unknown; + status: 'running' | 'done' | 'error'; + text: string; + table: AgentTable | null; + /** Provider API failures the engine reported while the tool ran. */ + engineNotes: string[]; + elapsedMs: number | null; + approval: ApprovalState | null; +} + +export type ChatItem = + | { kind: 'user'; key: string; text: string } + | { + kind: 'assistant'; + key: string; + text: string; + /** Set while the text arrives in pieces, so the pieces find their message. */ + messageId?: string; + } + | ToolItem + | { kind: 'notice'; key: string; text: string; tone: 'info' | 'warn' | 'error' } + /** What a turn used, as the provider counted it. Known when the turn ends. */ + | { kind: 'usage'; key: string; usage: TokenUsage } + | { + kind: 'session'; + key: string; + mode: SafetyMode; + protocolVersion: string; + tools: number; + /** The delegated agent that opened the session, when there is one. */ + agent?: string; + agentVersion?: string; + /** The protocol a delegated agent is driven over. */ + agentProtocol?: string; + /** The model that agent says it uses. */ + model?: string | null; + }; + +export interface ChatState { + items: ChatItem[]; + /** A turn is running. */ + busy: boolean; + /** Counter for item keys. */ + next: number; +} + +export const emptyChat: ChatState = { items: [], busy: false, next: 0 }; + +function push(state: ChatState, build: (key: string) => ChatItem): ChatState { + return { + ...state, + items: [...state.items, build(`item-${state.next}`)], + next: state.next + 1, + }; +} + +function mapTools(state: ChatState, change: (item: ToolItem) => ToolItem): ChatState { + return { + ...state, + items: state.items.map((item) => (item.kind === 'tool' ? change(item) : item)), + }; +} + +/** The operator sent a message, which starts a turn. */ +export function userSent(state: ChatState, text: string): ChatState { + return { ...push(state, (key) => ({ kind: 'user', key, text })), busy: true }; +} + +/** Applies one host event. */ +export function applyAgentEvent(state: ChatState, event: AgentEvent): ChatState { + switch (event.event) { + case 'sessionStarted': + return push(state, (key) => ({ kind: 'session', key, ...event.data })); + case 'delegateStarted': + return push(state, (key) => ({ + kind: 'session', + key, + mode: event.data.mode, + protocolVersion: '', + tools: event.data.tools, + agent: event.data.agent, + agentVersion: event.data.version, + agentProtocol: event.data.protocol, + model: event.data.model, + })); + case 'assistantText': + return push(state, (key) => ({ kind: 'assistant', key, text: event.data.text })); + case 'assistantDelta': { + // Add the piece to its message. A tool call can sit between two + // messages, so look back for it, not only at the last item. + for (let index = state.items.length - 1; index >= 0; index -= 1) { + const item = state.items[index]; + if (item?.kind === 'assistant' && item.messageId === event.data.id) { + const items = state.items.slice(); + items[index] = { ...item, text: item.text + event.data.text }; + return { ...state, items }; + } + } + return push(state, (key) => ({ + kind: 'assistant', + key, + text: event.data.text, + messageId: event.data.id, + })); + } + case 'toolCallStarted': + return push(state, (key) => ({ + kind: 'tool', + key, + callId: event.data.id, + tool: event.data.tool, + agent: event.data.agent ?? null, + step: event.data.step, + sql: event.data.sql, + arguments: event.data.arguments, + status: 'running', + text: '', + table: null, + engineNotes: [], + elapsedMs: null, + approval: null, + })); + case 'approvalRequested': { + // The engine asks while the tool call it gates is running. Several + // calls can be running at once, so find the one that sent this + // statement: same SQL, same tool, and no prompt of its own yet. If + // none matches, take the newest call still waiting for a result. + const request = event.data.request; + const open = state.items.filter( + (item): item is ToolItem => + item.kind === 'tool' && item.status === 'running' && item.approval === null, + ); + const target = + open.find( + (item) => + request.sql !== null && + item.sql === request.sql && + (request.tool === null || item.tool === request.tool), + ) ?? open.at(-1); + if (!target) { + // Nothing to attach it to. It still has to be answerable. + return push(state, (key) => ({ + kind: 'tool', + key, + callId: event.data.request.id, + tool: event.data.request.tool ?? 'approval', + agent: null, + step: null, + sql: event.data.request.sql, + arguments: {}, + status: 'running', + text: '', + table: null, + engineNotes: [], + elapsedMs: null, + approval: { request: event.data.request, decision: 'pending' }, + })); + } + return mapTools(state, (item) => + item.key === target.key + ? { ...item, approval: { request: event.data.request, decision: 'pending' } } + : item, + ); + } + case 'toolCallFinished': + return mapTools(state, (item) => + item.callId === event.data.id && item.status === 'running' + ? { + ...item, + status: event.data.isError ? 'error' : 'done', + text: event.data.text, + table: event.data.table, + engineNotes: event.data.engineNotes, + elapsedMs: event.data.elapsedMs, + // A prompt that was still open when the call ended was dismissed. + approval: + item.approval?.decision === 'pending' + ? { ...item.approval, decision: 'cancel' } + : item.approval, + } + : item, + ); + case 'notice': + return push(state, (key) => ({ + kind: 'notice', + key, + text: event.data.message, + tone: 'warn', + })); + } +} + +/** The operator answered an approval prompt. */ +export function approvalAnswered( + state: ChatState, + approvalId: string, + decision: ApprovalDecision, +): ChatState { + return mapTools(state, (item) => + item.approval?.request.id === approvalId && item.approval.decision === 'pending' + ? { ...item, approval: { ...item.approval, decision } } + : item, + ); +} + +function settle(state: ChatState): ChatState { + // Anything still marked running when the turn ends did not finish. + return mapTools({ ...state, busy: false }, (item) => + item.status === 'running' + ? { + ...item, + status: 'error', + text: item.text || 'This did not finish.', + approval: + item.approval?.decision === 'pending' + ? { ...item.approval, decision: 'cancel' } + : item.approval, + } + : item, + ); +} + +/** The turn ended. */ +export function turnFinished(state: ChatState, summary: TurnSummary): ChatState { + let next = settle(state); + // Kept only when the provider reported a count. Not every one does. + const { usage } = summary; + if (usage.inputTokens !== null || usage.outputTokens !== null) { + next = push(next, (key) => ({ kind: 'usage', key, usage })); + } + if (summary.stopped) { + next = push(next, (key) => ({ + kind: 'notice', + key, + tone: 'warn', + text: 'Stopped. A statement the engine had already started may still complete.', + })); + } else if (summary.stop.kind === 'refused') { + const detail = summary.stop.detail; + next = push(next, (key) => ({ kind: 'notice', key, tone: 'warn', text: detail })); + } else if (summary.stop.kind === 'maxTokens') { + next = push(next, (key) => ({ + kind: 'notice', + key, + tone: 'warn', + text: 'The reply was cut off by the output limit. Ask it to continue.', + })); + } + return next; +} + +/** The turn failed before it could finish, for example a rejected API key. */ +export function turnFailed(state: ChatState, error: HostError): ChatState { + return push(settle(state), (key) => ({ + kind: 'notice', + key, + tone: 'error', + text: error.message, + })); +} + +/** The approval prompts that are waiting for an answer. */ +export function pendingApprovals(state: ChatState): ApprovalRequest[] { + return state.items.flatMap((item) => + item.kind === 'tool' && item.approval?.decision === 'pending' ? [item.approval.request] : [], + ); +} + +/** A short name for the conversation: the start of the operator's first message. */ +export function chatTitle(state: ChatState, maxLength = 44): string | null { + const first = state.items.find((item) => item.kind === 'user'); + if (first?.kind !== 'user') { + return null; + } + const line = first.text.replace(/\s+/g, ' ').trim(); + return line.length > maxLength ? `${line.slice(0, maxLength - 3).trimEnd()}...` : line; +} + +/** Grows as the conversation does, including while a reply is being written. */ +export function chatProgress(state: ChatState): number { + const last = state.items[state.items.length - 1]; + const tail = last && 'text' in last ? last.text.length : 0; + return state.items.length * 100_000 + tail; +} + +export type Segment = + | { kind: 'text'; text: string } + | { + kind: 'code'; + language: string; + code: string; + /** The closing fence has not arrived: the block is still being written. */ + open?: boolean; + }; + +/** A fence that opens and is not closed before the text ends. */ +const OPEN_FENCE = /```([A-Za-z0-9_+-]*)(?:[ \t]*\r?\n([\s\S]*))?$/; + +/** + * Splits assistant text into prose and fenced code blocks, so that SQL the + * model proposes can be shown as code and opened in the editor, and a chart + * block can be drawn. + * + * A reply arrives in pieces. A fence that is open at the end of the text is + * a block still being written, and is marked as such, so that half a block + * is never shown as prose. + */ +export function splitFences(text: string): Segment[] { + const segments: Segment[] = []; + const pushText = (prose: string) => { + if (prose.trim() !== '') { + segments.push({ kind: 'text', text: prose.trim() }); + } + }; + const fence = /```([A-Za-z0-9_+-]*)[ \t]*\r?\n([\s\S]*?)(?:\r?\n)?```/g; + let last = 0; + for (const match of text.matchAll(fence)) { + pushText(text.slice(last, match.index)); + segments.push({ kind: 'code', language: (match[1] ?? '').toLowerCase(), code: match[2] ?? '' }); + last = match.index + match[0].length; + } + const rest = text.slice(last); + const open = OPEN_FENCE.exec(rest); + if (open) { + pushText(rest.slice(0, open.index)); + segments.push({ + kind: 'code', + language: (open[1] ?? '').toLowerCase(), + code: open[2] ?? '', + open: true, + }); + } else { + pushText(rest); + } + return segments; +} + +/** True for a code block worth offering to the editor. */ +export function looksLikeSql(segment: Segment): boolean { + if (segment.kind !== 'code') { + return false; + } + if (segment.language === 'sql' || segment.language === 'iql' || segment.language === 'stackql') { + return true; + } + return ( + segment.language === '' && + /^\s*(select|insert|update|delete|replace|exec|show|describe|registry|with)\b/i.test( + segment.code, + ) + ); +} + +const TOOL_TITLES: Record = { + server_info: 'Server info', + list_providers: 'List providers', + list_services: 'List services', + list_resources: 'List resources', + list_methods: 'List methods', + describe_method: 'Describe method', + validate_select_query: 'Validate query', + run_select_query: 'Run query', + run_mutation_query: 'Run mutation', + run_lifecycle_operation: 'Run lifecycle operation', + list_registry: 'List registry', + pull_provider: 'Install provider', + reload_credentials: 'Reload credentials', + query_library_search: 'Search query library', + query_library_get: 'Get query library entry', + // Not an engine tool: a delegated agent handing part of the work to a + // subagent. + subagent: 'Subagent', +}; + +export function toolTitle(tool: string): string { + return TOOL_TITLES[tool] ?? tool; +} + +/** A one-line summary of a tool's arguments, for tools that take no SQL. */ +export function argumentSummary(args: unknown): string { + if (typeof args !== 'object' || args === null) { + return ''; + } + return Object.entries(args as Record) + .filter(([key, value]) => key !== 'sql' && value !== null && value !== '') + .map(([key, value]) => `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`) + .join(', '); +} + +export const SAFETY_MODES: { mode: SafetyMode; label: string; description: string }[] = [ + { + mode: 'read_only', + label: 'Read only', + description: 'Queries run. Changes are refused by the engine.', + }, + { + mode: 'safe', + label: 'Safe', + description: 'Queries run. Each change needs your approval before it runs.', + }, + { + mode: 'delete_safe', + label: 'Delete safe', + description: 'Queries and changes run. DELETE and EXEC need your approval.', + }, + { + mode: 'full_access', + label: 'Full access', + description: 'Everything runs without approval.', + }, +]; + +/** + * What the modes come to with a delegated agent. It cannot pass the + * engine's approval prompt on, so the engine refuses where it would ask. + */ +const DELEGATED_DESCRIPTIONS: Record = { + read_only: 'Queries run. Changes are refused by the engine.', + safe: 'Queries run. Changes are refused by the engine, because this backend cannot show the approval prompt.', + delete_safe: + 'Queries and changes run. DELETE and EXEC are refused by the engine, because this backend cannot show the approval prompt.', + full_access: 'Everything runs without approval.', +}; + +/** What a safety mode means for the backend in use. */ +export function modeDescription(mode: SafetyMode, delegated: boolean): string { + if (delegated) { + return DELEGATED_DESCRIPTIONS[mode]; + } + return SAFETY_MODES.find((option) => option.mode === mode)?.description ?? ''; +} diff --git a/src/lib/cli.test.ts b/src/lib/cli.test.ts new file mode 100644 index 0000000..da34c31 --- /dev/null +++ b/src/lib/cli.test.ts @@ -0,0 +1,97 @@ +import { describe, expect, it } from 'vitest'; +import { connectionString, execCommand, type CliInput } from './cli'; + +const windows: CliInput = { + binary: 'C:\\Program Files\\StackQL\\stackql.exe', + approot: 'C:\\Users\\me\\.stackql', + envFile: null, + sql: "SELECT login FROM github.orgs.orgs WHERE org = 'stackql';", +}; + +const mac: CliInput = { + binary: '/usr/local/bin/stackql', + approot: '/Users/me/Library/Application Support/io.stackql.workbench/engine', + envFile: '/Users/me/.stackql.env', + sql: "SELECT login FROM github.orgs.orgs WHERE org = 'stackql';", +}; + +describe('execCommand for PowerShell', () => { + it('puts the statement in single quotes, with its own quotes doubled', () => { + expect(execCommand('powershell', windows)).toBe( + "& 'C:\\Program Files\\StackQL\\stackql.exe' exec --approot 'C:\\Users\\me\\.stackql' -- 'SELECT login FROM github.orgs.orgs WHERE org = ''stackql'';'", + ); + }); + + it('keeps a statement of several lines, comments included, as it is', () => { + const sql = "-- repositories\nSELECT name\nFROM github.repos.repos\nWHERE org = 'stackql';"; + expect(execCommand('powershell', { ...windows, sql })).toBe( + "& 'C:\\Program Files\\StackQL\\stackql.exe' exec --approot 'C:\\Users\\me\\.stackql' -- '-- repositories\nSELECT name\nFROM github.repos.repos\nWHERE org = ''stackql'';'", + ); + }); + + it('goes through a temporary file when the statement holds a double quote', () => { + const sql = 'SELECT "name" FROM github.repos.repos WHERE org = \'stackql\';'; + expect(execCommand('powershell', { ...windows, sql })).toBe( + [ + '$query = New-TemporaryFile', + "[IO.File]::WriteAllText($query.FullName, @'", + sql, + "'@)", + "& 'C:\\Program Files\\StackQL\\stackql.exe' exec --approot 'C:\\Users\\me\\.stackql' -i $query.FullName", + 'Remove-Item $query', + ].join('\n'), + ); + }); + + it('does not use a here-string that the statement would end early', () => { + const sql = 'SELECT "a"\n\'@ FROM x;'; + expect(execCommand('powershell', { ...windows, sql })).not.toContain('New-TemporaryFile'); + }); + + it('names the credentials file when there is one, and leaves out what is not set', () => { + expect( + execCommand('powershell', { + ...windows, + envFile: "C:\\it's here\\.env", + sql: 'SHOW PROVIDERS;', + }), + ).toBe( + "& 'C:\\Program Files\\StackQL\\stackql.exe' exec --approot 'C:\\Users\\me\\.stackql' --env.file 'C:\\it''s here\\.env' -- 'SHOW PROVIDERS;'", + ); + expect(execCommand('powershell', { ...windows, approot: null, sql: ' SHOW PROVIDERS; ' })).toBe( + "& 'C:\\Program Files\\StackQL\\stackql.exe' exec -- 'SHOW PROVIDERS;'", + ); + }); +}); + +describe('connectionString', () => { + it('names the address, with no TLS', () => { + expect(connectionString('127.0.0.1:50262')).toBe( + 'postgres://stackql@127.0.0.1:50262/stackql?sslmode=disable', + ); + expect(connectionString(' localhost:5466 ')).toBe( + 'postgres://stackql@localhost:5466/stackql?sslmode=disable', + ); + }); + + it('has nothing to offer for anything that is not a host and a port', () => { + for (const bad of ['', '127.0.0.1', 'http://127.0.0.1:5466', '127.0.0.1:port', 'a b:1']) { + expect(connectionString(bad), bad).toBeNull(); + } + }); +}); + +describe('execCommand for a POSIX shell', () => { + it('puts every part in single quotes and closes them around a quote', () => { + expect(execCommand('posix', mac)).toBe( + "'/usr/local/bin/stackql' exec --approot '/Users/me/Library/Application Support/io.stackql.workbench/engine' --env.file '/Users/me/.stackql.env' -- 'SELECT login FROM github.orgs.orgs WHERE org = '\\''stackql'\\'';'", + ); + }); + + it('passes double quotes, dollars and backticks through untouched', () => { + const sql = 'SELECT "name", \'$HOME\', `x` FROM t;'; + expect(execCommand('posix', { ...mac, approot: null, envFile: null, sql })).toBe( + "'/usr/local/bin/stackql' exec -- 'SELECT \"name\", '\\''$HOME'\\'', `x` FROM t;'", + ); + }); +}); diff --git a/src/lib/cli.ts b/src/lib/cli.ts new file mode 100644 index 0000000..c47b105 --- /dev/null +++ b/src/lib/cli.ts @@ -0,0 +1,82 @@ +// A `stackql exec` command for a statement, written for the shell the +// operator will paste it into. The shapes were tested in Windows +// PowerShell 5.1, PowerShell 7 and a POSIX shell. See docs/spike-pgwire.md. + +export type Shell = 'powershell' | 'posix'; + +export interface CliInput { + /** The full path of the stackql binary. */ + binary: string; + /** The engine's data folder, so the command sees the same providers. */ + approot: string | null; + /** The credentials file from settings, when one is set. */ + envFile: string | null; + sql: string; +} + +const powershellQuote = (text: string) => `'${text.replace(/'/g, "''")}'`; +const posixQuote = (text: string) => `'${text.replace(/'/g, `'\\''`)}'`; + +function flags(input: CliInput, quote: (text: string) => string): string { + return [ + ...(input.approot ? [`--approot ${quote(input.approot)}`] : []), + ...(input.envFile ? [`--env.file ${quote(input.envFile)}`] : []), + ].join(' '); +} + +const join = (parts: string[]) => parts.filter((part) => part !== '').join(' '); + +/** + * PowerShell. A statement goes in single quotes, after `--` so one that + * starts with a comment is not read as a flag. + * + * The two PowerShell generations pass a double quote to a program in + * different ways, and no one spelling works in both. A statement with a + * double quote in it is therefore written to a temporary file from a + * here-string, which both pass through untouched. + */ +function powershell(input: CliInput, sql: string): string { + const program = `& ${powershellQuote(input.binary)} exec`; + const options = flags(input, powershellQuote); + // A line starting with '@ would end the here-string early. + const fitsHereString = !/^'@/m.test(sql); + if (!sql.includes('"') || !fitsHereString) { + return join([program, options, '--', powershellQuote(sql)]); + } + return [ + '$query = New-TemporaryFile', + "[IO.File]::WriteAllText($query.FullName, @'", + sql, + "'@)", + join([program, options, '-i $query.FullName']), + 'Remove-Item $query', + ].join('\n'); +} + +function posix(input: CliInput, sql: string): string { + return join([ + `${posixQuote(input.binary)} exec`, + flags(input, posixQuote), + '--', + posixQuote(sql), + ]); +} + +/** + * A connection string for the engine's pg wire address, for example + * `127.0.0.1:5466`. The server has no authentication and no TLS, and takes + * any user and database name. Null when the address is not host and port. + */ +export function connectionString(endpoint: string): string | null { + const match = /^([\w.-]+|\[[0-9a-fA-F:]+\]):(\d{1,5})$/.exec(endpoint.trim()); + if (!match) { + return null; + } + return `postgres://stackql@${match[1]}:${match[2]}/stackql?sslmode=disable`; +} + +/** The command for `shell`. The statement is passed on exactly as written. */ +export function execCommand(shell: Shell, input: CliInput): string { + const sql = input.sql.trim(); + return shell === 'powershell' ? powershell(input, sql) : posix(input, sql); +} diff --git a/src/lib/completion.test.ts b/src/lib/completion.test.ts new file mode 100644 index 0000000..a5870cc --- /dev/null +++ b/src/lib/completion.test.ts @@ -0,0 +1,237 @@ +import { describe, expect, it } from 'vitest'; +import { + EMPTY_CATALOG, + catalogFrom, + currentStatement, + sampleStatement, + statementAt, + suggest, + type Catalog, +} from './completion'; +import { + fieldNodes, + methodGroupNodes, + methodNodes, + providerNodes, + resourceNodes, + serviceNodes, + type ChildState, + type TreeNode, +} from './explorerTree'; + +const catalog: Catalog = { + providers: ['github', 'aws'], + services: (provider) => (provider === 'github' ? ['repos', 'orgs'] : null), + resources: (provider, service) => + provider === 'github' && service === 'repos' ? ['repos', 'branches', 'my-res'] : null, + fields: (provider, service, resource) => + provider === 'github' && service === 'repos' && resource === 'repos' + ? [ + { name: 'name', type: 'string' }, + { name: 'stargazers_count', type: 'integer' }, + ] + : null, +}; + +const labels = (before: string, statement = before, explicit = false) => + suggest(catalog, before, statement, explicit)?.options.map((option) => option.label) ?? null; + +describe('suggest: names', () => { + it('offers providers after FROM, in order', () => { + expect(labels('SELECT * FROM ')).toEqual(['aws', 'github']); + expect(suggest(catalog, 'SELECT * FROM gi', 'SELECT * FROM gi', false)).toMatchObject({ + replace: 2, + options: [ + { label: 'aws', kind: 'provider' }, + { label: 'github', kind: 'provider' }, + ], + }); + }); + + it('offers the next level after a dot', () => { + expect(labels('SELECT * FROM github.')).toEqual(['orgs', 'repos']); + expect(labels('SELECT * FROM github.repos.')).toEqual(['branches', 'my-res', 'repos']); + expect(suggest(catalog, 'SELECT * FROM github.repos.br', '', false)?.replace).toBe(2); + }); + + it('offers nothing for a level that has not been loaded', () => { + expect(labels('SELECT * FROM aws.')).toBeNull(); + expect(labels('SELECT * FROM github.orgs.')).toBeNull(); + expect(labels('SELECT * FROM github.repos.repos.')).toBeNull(); + }); + + it('knows the other keywords that take a name', () => { + for (const lead of [ + 'INSERT INTO ', + 'UPDATE ', + 'DESCRIBE ', + 'DESCRIBE EXTENDED ', + 'DESCRIBE METHOD ', + 'EXEC ', + 'SELECT a FROM x.y.z JOIN ', + 'SHOW SERVICES IN ', + 'SHOW EXTENDED RESOURCES IN ', + ]) { + expect(labels(lead), lead).toEqual(['aws', 'github']); + } + }); + + it('does not take the IN of a WHERE clause for one', () => { + expect(labels('SELECT name FROM github.repos.repos WHERE org IN ')).toBeNull(); + }); + + it('reads a quoted name', () => { + expect(labels('SELECT * FROM "github".')).toEqual(['orgs', 'repos']); + expect(labels('SELECT * FROM "github"."repos".')).toEqual(['branches', 'my-res', 'repos']); + }); +}); + +describe('suggest: fields', () => { + const statement = "SELECT FROM github.repos.repos WHERE org = 'stackql'"; + + it('offers the fields of the resource the statement names, in the select list', () => { + expect(labels('SELECT na', statement)).toEqual(['name', 'stargazers_count']); + expect(suggest(catalog, 'SELECT na', statement, false)).toMatchObject({ + replace: 2, + options: [ + { label: 'name', kind: 'field', detail: 'string' }, + { label: 'stargazers_count', kind: 'field', detail: 'integer' }, + ], + }); + }); + + it('offers them in WHERE too', () => { + const full = 'SELECT name FROM github.repos.repos WHERE st'; + expect(labels(full, full)).toEqual(['name', 'stargazers_count']); + }); + + it('offers them after an alias and a dot', () => { + const full = 'SELECT r. FROM github.repos.repos r'; + expect(labels('SELECT r.', full)).toEqual(['name', 'stargazers_count']); + }); + + it('waits to be asked when nothing has been typed', () => { + expect(labels('SELECT ', statement)).toBeNull(); + expect(labels('SELECT ', statement, true)).toEqual(['name', 'stargazers_count']); + }); + + it('offers nothing when the fields of the resource have not been loaded', () => { + const full = 'SELECT na FROM github.repos.branches'; + expect(labels('SELECT na', full)).toBeNull(); + expect(labels('SELECT na', 'SELECT na')).toBeNull(); + }); +}); + +describe('suggest: where it stays quiet', () => { + it('offers nothing inside a string or a comment', () => { + expect(labels("SELECT * FROM github.repos.repos WHERE org = 'gi")).toBeNull(); + expect(labels('-- FROM ')).toBeNull(); + expect(labels("SELECT '--' FROM ")).toEqual(['aws', 'github']); + }); + + it('offers nothing with nothing loaded', () => { + expect(suggest(EMPTY_CATALOG, 'SELECT * FROM ', 'SELECT * FROM ', true)).toBeNull(); + }); +}); + +describe('currentStatement', () => { + it('takes the statement around the cursor', () => { + const text = 'SHOW PROVIDERS; SELECT a FROM x.y.z WHERE b = 1; SHOW VERSION'; + const cursor = text.indexOf('FROM'); + expect(currentStatement(text, cursor)).toEqual({ + before: ' SELECT a ', + statement: ' SELECT a FROM x.y.z WHERE b = 1', + }); + expect(currentStatement(text, text.length).statement).toBe(' SHOW VERSION'); + expect(currentStatement('SELECT 1', 3)).toEqual({ before: 'SEL', statement: 'SELECT 1' }); + }); +}); + +describe('statementAt', () => { + const text = 'SHOW PROVIDERS;\nSHOW VERSION;\n'; + + it('takes the statement the cursor is in', () => { + expect(statementAt(text, 4)).toBe('SHOW PROVIDERS'); + expect(statementAt(text, text.indexOf('VERSION'))).toBe('SHOW VERSION'); + }); + + it('takes the statement that has just ended when the cursor follows its semicolon', () => { + expect(statementAt(text, text.length)).toBe('SHOW VERSION'); + expect(statementAt(text, 'SHOW PROVIDERS;'.length)).toBe('SHOW PROVIDERS'); + expect(statementAt('SHOW VERSION ; ', 16)).toBe('SHOW VERSION'); + }); + + it('has nothing to give for an empty editor', () => { + expect(statementAt('', 0)).toBe(''); + expect(statementAt(' ;; ', 4)).toBe(''); + }); +}); + +describe('catalogFrom', () => { + const path = { provider: 'github', service: 'repos', resource: 'repos' }; + const roots = providerNodes([{ name: 'github', version: 'v1' }]); + const services = serviceNodes('github', [ + { name: 'repos', id: 'repos:v1', title: 'repos API', description: '' }, + ]); + const resources = resourceNodes('github', 'repos', [ + { name: 'repos', id: 'github.repos.repos', description: '' }, + ]); + const methods = methodNodes(path, [ + { name: 'list_for_org', sqlVerb: 'SELECT', requiredParams: ['org'], description: '' }, + ]); + const loaded = (nodes: TreeNode[]): ChildState => ({ status: 'loaded', nodes }); + + it('reads names from what is loaded and nothing from what is not', () => { + const children = new Map([ + ['p:github', loaded(services)], + ['s:github.repos', { status: 'loading' }], + ]); + const made = catalogFrom(roots, children); + expect(made.providers).toEqual(['github']); + expect(made.services('github')).toEqual(['repos']); + expect(made.services('aws')).toBeNull(); + expect(made.resources('github', 'repos')).toBeNull(); + expect(made.fields('github', 'repos', 'repos')).toBeNull(); + }); + + it('gathers fields from the resource and from the methods that have been opened', () => { + const groups = methodGroupNodes({ ...path, method: 'list_for_org' }, [ + { name: 'org', type: 'string', paramType: 'input_required', shape: '', description: '' }, + { name: 'name', type: 'string', paramType: 'output', shape: '', description: '' }, + { name: 'forks', type: 'integer', paramType: 'output', shape: '', description: '' }, + ]); + const children = new Map([ + ['p:github', loaded(services)], + ['s:github.repos', loaded(resources)], + [ + 'fg:github.repos.repos', + loaded(fieldNodes(path, [{ name: 'name', type: 'string', description: '' }])), + ], + ['mg:github.repos.repos', loaded(methods)], + ['m:github.repos.repos.list_for_org', loaded(groups)], + ]); + const made = catalogFrom(roots, children); + expect(made.resources('github', 'repos')).toEqual(['repos']); + expect(made.fields('github', 'repos', 'repos')).toEqual([ + { name: 'name', type: 'string' }, + { name: 'org', type: 'required string' }, + { name: 'forks', type: 'integer' }, + ]); + }); +}); + +describe('sampleStatement', () => { + it('names an installed provider', () => { + expect(sampleStatement(['homebrew', 'github'])).toContain('-- SHOW SERVICES IN github;'); + }); + + it('points at the registry when nothing is installed', () => { + expect(sampleStatement([])).toContain('-- REGISTRY LIST;'); + }); + + it('is all comments, so running it does nothing', () => { + for (const text of [sampleStatement(['github']), sampleStatement([])]) { + expect(text.split('\n').every((line) => line.startsWith('--'))).toBe(true); + } + }); +}); diff --git a/src/lib/completion.ts b/src/lib/completion.ts new file mode 100644 index 0000000..b351192 --- /dev/null +++ b/src/lib/completion.ts @@ -0,0 +1,231 @@ +// Completion for the editor, from what the explorer has already loaded. +// Nothing here asks the engine for anything, so a keystroke costs nothing. +// A level that has not been opened in the explorer offers no names. + +import type { ChildState, TreeNode } from './explorerTree'; + +export interface FieldInfo { + name: string; + type: string; +} + +/** The names the explorer holds. A lookup is null when that level is not loaded. */ +export interface Catalog { + providers: string[]; + services: (provider: string) => string[] | null; + resources: (provider: string, service: string) => string[] | null; + fields: (provider: string, service: string, resource: string) => FieldInfo[] | null; +} + +export const EMPTY_CATALOG: Catalog = { + providers: [], + services: () => null, + resources: () => null, + fields: () => null, +}; + +/** Reads the explorer's loaded nodes as a catalog. */ +export function catalogFrom(roots: TreeNode[], children: ReadonlyMap): Catalog { + const loaded = (id: string): TreeNode[] | null => { + const state = children.get(id); + return state?.status === 'loaded' ? state.nodes : null; + }; + return { + providers: roots.map((root) => root.label), + services: (provider) => loaded(`p:${provider}`)?.map((node) => node.label) ?? null, + resources: (provider, service) => + loaded(`s:${provider}.${service}`)?.map((node) => node.label) ?? null, + fields: (provider, service, resource) => { + const name = `${provider}.${service}.${resource}`; + const found = new Map(); + for (const node of loaded(`fg:${name}`) ?? []) { + found.set(node.label, { name: node.label, type: node.detail }); + } + // What a method takes and returns counts too, where it has been opened. + for (const method of loaded(`mg:${name}`) ?? []) { + for (const group of loaded(method.id) ?? []) { + for (const param of group.children ?? []) { + if (!found.has(param.label)) { + found.set(param.label, { name: param.label, type: param.detail }); + } + } + } + } + return found.size > 0 ? [...found.values()] : null; + }, + }; +} + +export interface Suggestion { + label: string; + kind: 'provider' | 'service' | 'resource' | 'field'; + /** Shown beside the label: what it is, or a field's type. */ + detail: string; +} + +export interface Suggestions { + /** How many characters before the cursor the chosen option replaces. */ + replace: number; + options: Suggestion[]; +} + +/** The statement the cursor is in, and the part of it before the cursor. */ +export function currentStatement( + text: string, + cursor: number, +): { before: string; statement: string } { + const start = text.lastIndexOf(';', cursor - 1) + 1; + const next = text.indexOf(';', cursor); + return { + before: text.slice(start, cursor), + statement: text.slice(start, next === -1 ? text.length : next), + }; +} + +/** + * The statement to run when nothing is selected: the one the cursor is in, + * or the one that ends just before it when the cursor follows a semicolon. + */ +export function statementAt(text: string, cursor: number): string { + const { before, statement } = currentStatement(text, cursor); + const here = statement.trim(); + // On the line of a semicolon, with nothing typed after it. + const justEnded = before.trim() === '' && !before.includes('\n'); + if (here !== '' && !justEnded) { + return here; + } + const ended = text.slice(0, cursor).replace(/[\s;]+$/, ''); + const previous = ended === '' ? '' : currentStatement(text, ended.length).statement.trim(); + return previous !== '' ? previous : here; +} + +const PART = String.raw`(?:"[^"]*"|[A-Za-z_][\w-]*)`; +const TABLE = new RegExp( + String.raw`\b(?:from|join|into|update)\s+(${PART})\.(${PART})\.(${PART})`, + 'gi', +); +const unquote = (part: string) => part.replace(/^"/, '').replace(/"$/, ''); + +/** Keywords that are followed by the name of a provider, service or resource. */ +const BEFORE_A_NAME = new Set(['from', 'join', 'into', 'update', 'describe', 'desc', 'exec']); + +function inStringOrComment(before: string): boolean { + let quotes = 0; + for (const character of before) { + if (character === "'") { + quotes += 1; + } + } + if (quotes % 2 === 1) { + return true; + } + const line = before.slice(before.lastIndexOf('\n') + 1); + return line.replace(/'[^']*'/g, '').includes('--'); +} + +function expectsName(head: string, statement: string): boolean { + const last = /([A-Za-z_]+)\s*$/.exec(head)?.[1]?.toLowerCase() ?? ''; + const prior = /([A-Za-z_]+)\s+[A-Za-z_]+\s*$/.exec(head)?.[1]?.toLowerCase() ?? ''; + if (BEFORE_A_NAME.has(last)) { + return true; + } + if ((last === 'extended' || last === 'method') && (prior === 'describe' || prior === 'desc')) { + return true; + } + // SHOW SERVICES IN provider, and the like. Not the IN of a WHERE clause. + return last === 'in' && /^\s*show\b/i.test(statement); +} + +/** + * What to offer at the cursor. `before` is the statement up to the cursor + * and `statement` is all of it. `explicit` is true when the operator asked + * for completion, as opposed to it starting while they type. + * + * After a keyword that takes a name, and after a dot, the next level of + * the provider hierarchy is offered. Elsewhere the fields of the resources + * the statement names are offered. Null means there is nothing to add to + * the keywords. + */ +export function suggest( + catalog: Catalog, + before: string, + statement: string, + explicit: boolean, +): Suggestions | null { + if (inStringOrComment(before)) { + return null; + } + const word = /[\w".-]*$/.exec(before)?.[0] ?? ''; + const parts = word.split('.'); + const last = parts[parts.length - 1] ?? ''; + const names = parts.slice(0, -1).map(unquote); + const named = expectsName(before.slice(0, before.length - word.length), statement); + const first = names[0]; + + if (named || (first !== undefined && catalog.providers.includes(first))) { + const [provider, service] = names; + const level: [string[] | null, Suggestion['kind']] = + provider === undefined + ? [catalog.providers, 'provider'] + : service === undefined + ? [catalog.services(provider), 'service'] + : names.length === 2 + ? [catalog.resources(provider, service), 'resource'] + : [null, 'resource']; + const [labels, kind] = level; + if (labels === null || labels.length === 0) { + return null; + } + return { + replace: last.length, + options: [...labels].sort().map((label) => ({ label, kind, detail: kind })), + }; + } + + // A column, perhaps after an alias and a dot. + if (last === '' && names.length === 0 && !explicit) { + return null; + } + const fields = new Map(); + for (const match of statement.matchAll(TABLE)) { + const [provider, service, resource] = match.slice(1).map((part) => unquote(part)); + if (provider === undefined || service === undefined || resource === undefined) { + continue; + } + for (const field of catalog.fields(provider, service, resource) ?? []) { + if (!fields.has(field.name)) { + fields.set(field.name, field); + } + } + } + if (fields.size === 0) { + return null; + } + return { + replace: last.length, + options: [...fields.values()].map((field) => ({ + label: field.name, + kind: 'field', + detail: field.type, + })), + }; +} + +/** + * What an empty editor shows: a commented statement that runs against an + * installed provider, or against the registry when nothing is installed. + */ +export function sampleStatement(providers: string[]): string { + const provider = [...providers].sort()[0]; + if (provider === undefined) { + return [ + '-- No provider is installed yet. This lists what the registry offers:', + '-- REGISTRY LIST;', + ].join('\n'); + } + return [ + '-- A statement to start from:', + `-- SHOW SERVICES IN ${provider};`, + '-- Or right-click a resource in the explorer and choose Generate SELECT.', + ].join('\n'); +} diff --git a/src/lib/conversation.test.ts b/src/lib/conversation.test.ts new file mode 100644 index 0000000..700f83d --- /dev/null +++ b/src/lib/conversation.test.ts @@ -0,0 +1,534 @@ +import { describe, expect, it } from 'vitest'; +import type { AgentEvent, AgentTable, ApprovalRequest, TurnSummary } from '../host/types'; +import { + applyAgentEvent, + approvalAnswered, + emptyChat, + toolTitle, + turnFailed, + turnFinished, + userSent, + type ChatState, +} from './chat'; +import { + callSummary, + conversationBlocks, + hasRows, + isHiddenCall, + presentsCharts, + stepsLabel, + usageDetail, + usageLabel, + type Block, + type StepsBlock, +} from './conversation'; + +const ended: TurnSummary = { + steps: 2, + toolCalls: 1, + stopped: false, + stop: { kind: 'endTurn' }, + // A provider that reports no counts, unless a test says otherwise. + usage: { inputTokens: null, outputTokens: null, cachedInputTokens: null }, +}; + +const table = (columns: string[], rows: (string | null)[][]): AgentTable => ({ + columns, + rows, + totalRows: rows.length, + truncated: false, +}); + +const started = (id: string, tool: string, sql: string | null, step = 1): AgentEvent => ({ + event: 'toolCallStarted', + data: { id, tool, arguments: sql ? { sql } : {}, sql, step }, +}); + +const finished = (id: string, result: AgentTable | null = null, isError = false): AgentEvent => ({ + event: 'toolCallFinished', + data: { + id, + isError, + text: isError ? 'syntax error at position 426' : 'ok', + table: result, + engineNotes: [], + elapsedMs: 12, + }, +}); + +const said = (text: string): AgentEvent => ({ event: 'assistantText', data: { text } }); + +function play(events: AgentEvent[], from: ChatState = userSent(emptyChat, 'hello')): ChatState { + return events.reduce(applyAgentEvent, from); +} + +const kinds = (blocks: Block[]) => blocks.map((block) => block.kind); + +function stepsOf(blocks: Block[]): StepsBlock { + const found = blocks.find((block): block is StepsBlock => block.kind === 'steps'); + if (!found) { + throw new Error('No steps in this conversation.'); + } + return found; +} + +const MONTHS = table( + ['month', 'issues'], + [ + ['2026-10', '13'], + ['2026-11', '8'], + ], +); + +describe('a turn that answers from one statement', () => { + const state = turnFinished( + play([ + started('c1', 'list_providers', null), + finished('c1', table(['name'], [['github']])), + said('I will count by month.'), + started('c2', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c2', MONTHS), + said('October was the busiest month.'), + ]), + ended, + ); + const blocks = conversationBlocks(state); + + it('is the message, the steps, the result and the answer', () => { + expect(kinds(blocks)).toEqual(['item', 'steps', 'result', 'answer']); + }); + + it('keeps every call and what was written between them as steps', () => { + const steps = stepsOf(blocks); + expect(steps.steps.map((step) => step.kind)).toEqual(['call', 'note', 'call']); + expect(steps.calls).toBe(2); + expect(steps.active).toBe(false); + expect(stepsLabel(steps, toolTitle)).toBe('2 steps'); + }); + + it('shows the last statement that returned rows, not the output of a lookup', () => { + const result = blocks.find((block) => block.kind === 'result'); + expect(result?.kind === 'result' && result.item.callId).toBe('c2'); + }); + + it('takes what was written after the last call as the answer', () => { + const answer = blocks.find((block) => block.kind === 'answer'); + expect(answer?.kind === 'answer' && answer.text).toBe('October was the busiest month.'); + }); +}); + +describe('a call that failed', () => { + const state = turnFinished( + play([ + started('c1', 'run_select_query', 'SELEC 1'), + finished('c1', null, true), + said('That did not parse. Trying again.'), + started('c2', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c2', MONTHS), + started('c3', 'run_select_query', 'SELECT nope'), + finished('c3', null, true), + said('Here is the count by month.'), + ]), + ended, + ); + const blocks = conversationBlocks(state); + + it('is not listed among the steps', () => { + const steps = stepsOf(blocks); + const calls = steps.steps.flatMap((step) => (step.kind === 'call' ? [step.item.callId] : [])); + expect(calls).toEqual(['c2']); + expect(steps.calls).toBe(1); + expect(stepsLabel(steps, toolTitle)).toBe('1 step'); + }); + + it('puts no error text anywhere in what is drawn', () => { + expect(JSON.stringify(blocks)).not.toContain('syntax error'); + }); + + it('is still in the chat state, where it ended as an error', () => { + const errors = state.items.filter((item) => item.kind === 'tool' && item.status === 'error'); + expect(errors).toHaveLength(2); + expect(errors.every((item) => item.kind === 'tool' && isHiddenCall(item))).toBe(true); + }); + + it('leaves no steps at all when every call failed', () => { + const none = conversationBlocks( + turnFinished( + play([ + started('c1', 'run_select_query', 'SELEC 1'), + finished('c1', null, true), + said('I could not run that, because the provider needs a sign-in.'), + ]), + ended, + ), + ); + expect(kinds(none)).toEqual(['item', 'answer']); + }); +}); + +describe('a call the operator was asked about', () => { + const request: ApprovalRequest = { + id: 'approval-1', + message: 'Approve run_mutation_query (mutation_delete)?', + tool: 'run_mutation_query', + queryClass: 'mutation_delete', + sql: 'DELETE FROM t', + }; + const asked = play([ + started('c1', 'run_mutation_query', 'DELETE FROM t'), + { event: 'approvalRequested', data: { request } }, + ]); + + it('marks the steps as waiting while the prompt is open', () => { + const steps = stepsOf(conversationBlocks(asked)); + expect(steps.waiting).toBe(true); + expect(steps.active).toBe(true); + }); + + it('stays among the steps when it then fails, because the decision was theirs', () => { + const declined = applyAgentEvent( + approvalAnswered(asked, 'approval-1', 'decline'), + finished('c1', null, true), + ); + const steps = stepsOf(conversationBlocks(turnFinished(declined, ended))); + expect(steps.steps).toHaveLength(1); + expect(steps.waiting).toBe(false); + const call = steps.steps[0]; + expect(call?.kind === 'call' && call.item.status).toBe('error'); + expect(call?.kind === 'call' && isHiddenCall(call.item)).toBe(false); + }); +}); + +describe('a turn that is still running', () => { + it('shows what is being written as the answer until a call follows it', () => { + const writing = play([said('Let me look.')]); + expect(kinds(conversationBlocks(writing))).toEqual(['item', 'answer']); + + const calling = applyAgentEvent(writing, started('c1', 'run_select_query', 'SELECT 1')); + const blocks = conversationBlocks(calling); + expect(kinds(blocks)).toEqual(['item', 'steps']); + const steps = stepsOf(blocks); + expect(steps.steps.map((step) => step.kind)).toEqual(['note', 'call']); + expect(steps.active).toBe(true); + expect(steps.running?.callId).toBe('c1'); + expect(stepsLabel(steps, toolTitle)).toBe('Working: Run query'); + }); + + it('puts the result under the steps as soon as there is one', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c1', MONTHS), + started('c2', 'run_select_query', 'SELECT 2'), + ]); + expect(kinds(conversationBlocks(state))).toEqual(['item', 'steps', 'result']); + expect(stepsLabel(stepsOf(conversationBlocks(state)), toolTitle)).toBe('Working: Run query'); + }); + + it('says only that it is working when no call is running', () => { + const between = play([started('c1', 'list_providers', null), finished('c1')]); + expect(stepsLabel(stepsOf(conversationBlocks(between)), toolTitle)).toBe('Working'); + }); +}); + +describe('a turn that ended without words after its last call', () => { + it('takes the last thing written as the answer', () => { + const state = turnFinished( + play([ + said('There are two months of data.'), + started('c1', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c1', MONTHS), + ]), + ended, + ); + // It is drawn below the steps and the result, where an answer goes. + const blocks = conversationBlocks(state); + expect(kinds(blocks)).toEqual(['item', 'steps', 'result', 'answer']); + const answer = blocks[blocks.length - 1]; + expect(answer?.kind === 'answer' && answer.text).toBe('There are two months of data.'); + }); + + it('keeps the notice of a turn that failed', () => { + const state = turnFailed(play([started('c1', 'run_select_query', 'SELECT 1')]), { + kind: 'agent', + message: 'The API key was rejected.', + }); + const blocks = conversationBlocks(state); + // The call never finished, so it ended as an error and is not listed. + expect(kinds(blocks)).toEqual(['item', 'item']); + const notice = blocks[1]; + expect(notice?.kind === 'item' && notice.item.kind === 'notice' && notice.item.text).toBe( + 'The API key was rejected.', + ); + }); +}); + +describe('an answer with a chart block', () => { + const chart = '```chart\n{"type":"bar","x":"month","y":["issues"]}\n```'; + const state = turnFinished( + play([ + started('c1', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c1', MONTHS), + said(`Issues by month:\n\n${chart}`), + ]), + ended, + ); + + it('is shown with its charts, and not with the table as well', () => { + expect(kinds(conversationBlocks(state))).toEqual(['item', 'steps', 'answer']); + }); + + it('is given the result sets a chart can be drawn from', () => { + const answer = conversationBlocks(state).find((block) => block.kind === 'answer'); + expect(answer?.kind === 'answer' && answer.tables.map((item) => item.callId)).toEqual(['c1']); + }); + + it('can draw from a result an earlier turn produced', () => { + const next = turnFinished( + [said(`Again as a line:\n\n${chart}`)].reduce( + applyAgentEvent, + userSent(state, 'now as a line'), + ), + ended, + ); + const blocks = conversationBlocks(next); + expect(kinds(blocks)).toEqual(['item', 'steps', 'answer', 'item', 'answer']); + const last = blocks[blocks.length - 1]; + expect(last?.kind === 'answer' && last.tables.map((item) => item.callId)).toEqual(['c1']); + }); + + it('counts a chart block that is still being written', () => { + expect(presentsCharts('Here:\n\n```chart\n{"type":"ba')).toBe(true); + expect(presentsCharts('```sql\nSELECT 1\n```')).toBe(false); + expect(presentsCharts('No blocks here.')).toBe(false); + }); +}); + +describe('several turns', () => { + it('each get their own steps and result', () => { + const first = turnFinished( + play([ + started('c1', 'run_select_query', 'SELECT 1 AS n'), + finished('c1', table(['n'], [['1']])), + said('One.'), + ]), + ended, + ); + const second = turnFinished( + [ + started('c2', 'run_select_query', 'SELECT 2 AS n'), + finished('c2', table(['n'], [['2']])), + said('Two.'), + ].reduce(applyAgentEvent, userSent(first, 'and again')), + ended, + ); + const blocks = conversationBlocks(second); + expect(kinds(blocks)).toEqual([ + 'item', + 'steps', + 'result', + 'answer', + 'item', + 'steps', + 'result', + 'answer', + ]); + const results = blocks.flatMap((block) => (block.kind === 'result' ? [block.item.callId] : [])); + expect(results).toEqual(['c1', 'c2']); + // Only the last turn can be the one that is running. + expect(blocks.every((block) => block.kind !== 'steps' || !block.active)).toBe(true); + }); +}); + +describe('the result sets a turn is shown with', () => { + const one = (n: string) => table(['n'], [[n]]); + const shown = (events: AgentEvent[]) => + conversationBlocks(turnFinished(play(events), ended)).flatMap((block) => + block.kind === 'result' ? [block.item.callId] : [], + ); + + it('are those of the statements the assistant asked for together, last', () => { + expect( + shown([ + // Looked up on the way, in an earlier step. + started('probe', 'run_select_query', 'SELECT 0', 1), + finished('probe', one('0')), + // Asked for together. + started('details', 'run_select_query', 'SELECT 1', 2), + started('count', 'run_select_query', 'SELECT 2', 2), + finished('count', one('2')), + finished('details', one('1')), + said('Here are both.'), + ]), + ).toEqual(['details', 'count']); + }); + + it('leave out a statement of that step that failed or returned nothing', () => { + expect( + shown([ + started('a', 'run_select_query', 'SELECT 1', 3), + started('b', 'run_select_query', 'SELEC 2', 3), + started('c', 'run_select_query', 'SELECT 3', 3), + finished('a', one('1')), + finished('b', null, true), + finished('c', table(['n'], [])), + said('One of them had rows.'), + ]), + ).toEqual(['a']); + }); + + it('are not the output of a lookup, which is not a statement', () => { + expect( + shown([ + started('q', 'run_select_query', 'SELECT 1', 1), + finished('q', one('1')), + started('meta', 'list_providers', null, 2), + finished('meta', table(['name'], [['github']])), + said('Done.'), + ]), + ).toEqual(['q']); + }); + + it('are at most four, the last four', () => { + const ids = ['a', 'b', 'c', 'd', 'e', 'f']; + expect( + shown([ + ...ids.map((id) => started(id, 'run_select_query', `SELECT '${id}'`, 1)), + ...ids.map((id) => finished(id, one(id))), + said('Many.'), + ]), + ).toEqual(['c', 'd', 'e', 'f']); + }); + + it('are none when the turn ran no statement that returned rows', () => { + expect( + shown([ + started('meta', 'list_providers', null, 1), + finished('meta', table(['name'], [['github']])), + said('GitHub is installed.'), + ]), + ).toEqual([]); + }); +}); + +describe('what a turn used', () => { + const usage = { inputTokens: 19353, outputTokens: 92, cachedInputTokens: 9533 }; + const counted = { ...ended, usage }; + + it('is said on the line that heads the steps', () => { + const blocks = conversationBlocks( + turnFinished( + play([ + started('c1', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c1', MONTHS), + said('Two months.'), + ]), + counted, + ), + ); + // No block of its own: the steps carry it. + expect(kinds(blocks)).toEqual(['item', 'steps', 'result', 'answer']); + expect(stepsOf(blocks).usage).toEqual(usage); + }); + + it('takes the place of the steps, above the answer, in a turn that has none', () => { + const blocks = conversationBlocks(turnFinished(play([said('Hello.')]), counted)); + expect(kinds(blocks)).toEqual(['item', 'usage', 'answer']); + const block = blocks[1]; + expect(block?.kind === 'usage' && block.usage).toEqual(usage); + }); + + it('is still said when every call failed and nothing was answered', () => { + const blocks = conversationBlocks( + turnFinished( + play([started('c1', 'run_select_query', 'SELEC 1'), finished('c1', null, true)]), + counted, + ), + ); + expect(kinds(blocks)).toEqual(['item', 'usage']); + }); + + it('belongs to its own turn', () => { + const first = turnFinished(play([said('One.')]), counted); + const second = turnFinished( + [ + started('c1', 'run_select_query', 'SELECT month, issues FROM t'), + finished('c1', MONTHS), + said('Two.'), + ].reduce(applyAgentEvent, userSent(first, 'again')), + { ...ended, usage: { inputTokens: 500, outputTokens: 7, cachedInputTokens: null } }, + ); + const blocks = conversationBlocks(second); + expect(kinds(blocks)).toEqual(['item', 'usage', 'answer', 'item', 'steps', 'result', 'answer']); + expect(stepsOf(blocks).usage?.inputTokens).toBe(500); + }); + + it('is not shown while the turn runs, since it is not known yet', () => { + const running = play([started('c1', 'run_select_query', 'SELECT 1')]); + expect(stepsOf(conversationBlocks(running)).usage).toBeNull(); + }); +}); + +describe('usageLabel and usageDetail', () => { + it('says the counts in full, with what was cached', () => { + expect(usageLabel({ inputTokens: 19353, outputTokens: 92, cachedInputTokens: 9533 })).toBe( + '19,353 tokens in (9,533 cached), 92 out', + ); + expect(usageLabel({ inputTokens: 1204, outputTokens: 86, cachedInputTokens: null })).toBe( + '1,204 tokens in, 86 out', + ); + // Nothing cached is nothing worth a bracket. + expect(usageLabel({ inputTokens: 1204, outputTokens: 86, cachedInputTokens: 0 })).toBe( + '1,204 tokens in, 86 out', + ); + }); + + it('leaves out a count the provider did not report', () => { + expect(usageLabel({ inputTokens: 300, outputTokens: null, cachedInputTokens: 150 })).toBe( + '300 tokens in (150 cached)', + ); + expect(usageLabel({ inputTokens: null, outputTokens: 40, cachedInputTokens: null })).toBe( + '40 tokens out', + ); + expect(usageLabel({ inputTokens: null, outputTokens: null, cachedInputTokens: 9 })).toBe(''); + }); + + it('explains that the counts cover every call to the model', () => { + const plain = usageDetail({ inputTokens: 10, outputTokens: 2, cachedInputTokens: null }); + expect(plain).toContain('added up over every call to the model'); + expect(plain).not.toContain('cache'); + expect(usageDetail({ inputTokens: 10, outputTokens: 2, cachedInputTokens: 4 })).toContain( + 'part of the tokens in', + ); + }); +}); + +describe('hasRows', () => { + it('is true only for a finished call with rows', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT 1'), + finished('c1', table(['n'], [])), + started('c2', 'run_select_query', 'SELECT 2'), + finished('c2', table(['n'], [['2']])), + started('c3', 'run_select_query', 'SELECT 3'), + ]); + const calls = state.items.flatMap((item) => (item.kind === 'tool' ? [item] : [])); + expect(calls.map(hasRows)).toEqual([false, true, false]); + }); +}); + +describe('callSummary', () => { + it('is the statement on one line, or the arguments, cut when long', () => { + const state = play([ + started('c1', 'run_select_query', 'SELECT a,\n b\nFROM t'), + started('c2', 'list_services', null), + ]); + const calls = state.items.flatMap((item) => (item.kind === 'tool' ? [item] : [])); + const [first, second] = calls; + if (!first || !second) { + throw new Error('Two calls were expected.'); + } + expect(callSummary(first, '')).toBe('SELECT a, b FROM t'); + expect(callSummary(second, 'provider: github')).toBe('provider: github'); + expect(callSummary(first, '', 12)).toBe('SELECT a,...'); + }); +}); diff --git a/src/lib/conversation.ts b/src/lib/conversation.ts new file mode 100644 index 0000000..b40b419 --- /dev/null +++ b/src/lib/conversation.ts @@ -0,0 +1,299 @@ +// How a conversation is laid out, worked out from the chat state. Pure +// functions, so the layout can be tested without a page. +// +// A turn is shown as its answer. What the assistant did on the way is kept +// in one list of steps, folded away once the turn has ended: the calls it +// made, each with its SQL and its result, and what it wrote between them. +// A call that failed is not listed. A model reads the error, corrects the +// statement and runs it again, and that is part of how it works, not +// something to put in front of the operator. The host writes every failed +// call to the app's log. + +import type { TokenUsage } from '../host/types'; +import { splitFences, type ChatItem, type ChatState, type ToolItem } from './chat'; + +export type Step = + /** A call the assistant made. */ + | { kind: 'call'; key: string; item: ToolItem } + /** What the assistant wrote before going on to another call. */ + | { kind: 'note'; key: string; text: string; tables: ToolItem[] }; + +type PlainItem = Extract; + +export interface StepsBlock { + kind: 'steps'; + key: string; + steps: Step[]; + /** How many of the steps are calls. */ + calls: number; + /** The turn these steps belong to is still running. */ + active: boolean; + /** A step is waiting for the operator's decision. */ + waiting: boolean; + /** The call that is running now, if one is. */ + running: ToolItem | null; + /** What the turn used, once it has ended and if the provider said. */ + usage: TokenUsage | null; +} + +export type Block = + | { kind: 'item'; key: string; item: PlainItem } + | StepsBlock + /** What a turn with no steps used. A turn with steps says it on their line. */ + | { kind: 'usage'; key: string; usage: TokenUsage } + /** A result set a turn is shown with, when its answer presents none itself. */ + | { kind: 'result'; key: string; item: ToolItem } + | { + kind: 'answer'; + key: string; + text: string; + /** The result sets a chart block in the text can be drawn from, oldest first. */ + tables: ToolItem[]; + }; + +/** + * A call that failed is left out, unless the operator was asked about it: + * then the call is theirs to see, with what they decided and how it ended. + */ +export function isHiddenCall(item: ToolItem): boolean { + return item.status === 'error' && item.approval === null; +} + +/** A call that finished with a result set that has something in it. */ +export function hasRows(item: ToolItem): boolean { + return ( + item.status === 'done' && + item.table !== null && + item.table.columns.length > 0 && + item.table.rows.length > 0 + ); +} + +/** A call that finished with a result set a chart could be drawn from. */ +function hasTable(item: ToolItem): boolean { + return item.status === 'done' && item.table !== null && item.table.columns.length > 0; +} + +/** True when the text holds a chart block, closed or still being written. */ +export function presentsCharts(text: string): boolean { + return splitFences(text).some( + (segment) => segment.kind === 'code' && segment.language === 'chart', + ); +} + +/** The turns of a conversation: each starts with what the operator sent. */ +function turns(items: ChatItem[]): ChatItem[][] { + const out: ChatItem[][] = []; + for (const item of items) { + const current = out[out.length - 1]; + if (item.kind === 'user' || !current) { + out.push([item]); + } else { + current.push(item); + } + } + return out; +} + +/** + * Which item of a turn is its answer: what the assistant wrote after its + * last call. While a turn runs that can still change, since a call may + * follow. A turn that has ended with a call last has no words after it, and + * then the last thing the assistant wrote is taken as the answer. + */ +function answerIndex(items: ChatItem[], active: boolean): number { + let lastText = -1; + let lastCall = -1; + items.forEach((item, index) => { + if (item.kind === 'assistant' && item.text.trim() !== '') { + lastText = index; + } else if (item.kind === 'tool') { + lastCall = index; + } + }); + if (lastText > lastCall) { + return lastText; + } + return active ? -1 : lastText; +} + +function addStep(block: StepsBlock, step: Step): void { + block.steps.push(step); + if (step.kind === 'call') { + block.calls += 1; + block.waiting ||= step.item.approval?.decision === 'pending'; + if (step.item.status === 'running') { + block.running = step.item; + } + } +} + +/** The most result sets a turn is shown with. The steps hold the rest. */ +export const MAX_SHOWN_RESULTS = 4; + +/** + * The result sets a turn is shown with: those of the last statement that + * returned rows, and of the statements the assistant asked for together + * with it. A question that takes two statements to answer is shown with + * both, and what the assistant looked up on the way to them is not. + */ +export function shownResults(items: ChatItem[]): ToolItem[] { + const withRows = items.filter( + (item): item is ToolItem => item.kind === 'tool' && item.sql !== null && hasRows(item), + ); + const last = withRows[withRows.length - 1]; + if (!last) { + return []; + } + const together = last.step === null ? [last] : withRows.filter((item) => item.step === last.step); + return together.slice(-MAX_SHOWN_RESULTS); +} + +/** + * Lays one turn out and adds its blocks. `tables` holds every result set so + * far, in every turn, and this turn's are added to it: a chart can be drawn + * from a result an earlier turn produced. + */ +function layoutTurn(items: ChatItem[], active: boolean, tables: ToolItem[], blocks: Block[]): void { + const answerAt = answerIndex(items, active); + const shown = shownResults(items); + const results = (): Block[] => + shown.map((item) => ({ kind: 'result', key: `result-${item.key}`, item })); + const steps: StepsBlock = { + kind: 'steps', + key: '', + steps: [], + calls: 0, + active, + waiting: false, + running: null, + usage: null, + }; + // Where the steps were put, once there is a first step to show. + let stepsAt = -1; + const step = (next: Step) => { + if (stepsAt < 0) { + steps.key = `steps-${next.key}`; + stepsAt = blocks.length; + blocks.push(steps); + } + addStep(steps, next); + }; + // Where the answer starts, its result sets included, once there is one. + let answerStart = -1; + const answer = (item: { key: string; text: string }) => { + answerStart = blocks.length; + // An answer that presents results itself is shown with those. + // Otherwise the turn's result sets go in front of it. + if (!presentsCharts(item.text)) { + blocks.push(...results()); + } + blocks.push({ kind: 'answer', key: item.key, text: item.text, tables: tables.slice() }); + }; + + // An answer that calls came after is drawn below them, like any other. + let held: { key: string; text: string } | null = null; + let answered = false; + // What the turn used, which the host says when the turn ends. + let used: Extract | null = null; + for (const [index, item] of items.entries()) { + if (item.kind === 'tool') { + if (hasTable(item)) { + tables.push(item); + } + if (!isHiddenCall(item)) { + step({ kind: 'call', key: item.key, item }); + } + } else if (item.kind === 'usage') { + used = item; + } else if (item.kind !== 'assistant') { + blocks.push({ kind: 'item', key: item.key, item }); + } else if (item.text.trim() === '') { + // Nothing was written. + } else if (index !== answerAt) { + step({ kind: 'note', key: item.key, text: item.text, tables: tables.slice() }); + } else if (items.slice(index + 1).some((later) => later.kind === 'tool')) { + held = item; + } else { + answer(item); + answered = true; + } + } + + if (held) { + answer(held); + } else if (!answered) { + // No answer yet, or none at all. The results go under the steps. + blocks.splice(stepsAt >= 0 ? stepsAt + 1 : blocks.length, 0, ...results()); + } + + if (used) { + if (stepsAt >= 0) { + // On the line that heads the steps, out of the way of the answer. + steps.usage = used.usage; + } else { + // A turn with no steps still used tokens. Its count takes the place + // the steps would have had, above the answer. + const at = answerStart >= 0 ? answerStart : blocks.length; + blocks.splice(at, 0, { kind: 'usage', key: used.key, usage: used.usage }); + } + } +} + +/** Lays the conversation out as blocks, in the order they are drawn. */ +export function conversationBlocks(state: ChatState): Block[] { + const blocks: Block[] = []; + const tables: ToolItem[] = []; + const all = turns(state.items); + all.forEach((items, turn) => { + layoutTurn(items, state.busy && turn === all.length - 1, tables, blocks); + }); + return blocks; +} + +/** What a step list is headed with. */ +export function stepsLabel(block: StepsBlock, title: (tool: string) => string): string { + if (block.active) { + return block.running ? `Working: ${title(block.running.tool)}` : 'Working'; + } + if (block.calls === 0) { + return 'Notes'; + } + return block.calls === 1 ? '1 step' : `${block.calls} steps`; +} + +const counted = (tokens: number) => tokens.toLocaleString('en-US'); + +/** + * What a turn used, in a few words: `19,353 tokens in (9,533 cached), 92 out`. + * A count the provider did not report is left out. Empty when it reported none. + */ +export function usageLabel(usage: TokenUsage): string { + const { inputTokens, outputTokens, cachedInputTokens } = usage; + const cached = + inputTokens !== null && cachedInputTokens !== null && cachedInputTokens > 0 + ? ` (${counted(cachedInputTokens)} cached)` + : ''; + if (inputTokens !== null && outputTokens !== null) { + return `${counted(inputTokens)} tokens in${cached}, ${counted(outputTokens)} out`; + } + if (inputTokens !== null) { + return `${counted(inputTokens)} tokens in${cached}`; + } + return outputTokens === null ? '' : `${counted(outputTokens)} tokens out`; +} + +/** What those counts are, for whoever stops on them to ask. */ +export function usageDetail(usage: TokenUsage): string { + const cached = + usage.cachedInputTokens !== null && usage.cachedInputTokens > 0 + ? ' Cached tokens are part of the tokens in: the provider had seen them before and read them from its cache.' + : ''; + return `What the model was sent and what it wrote in this turn, as the provider counted it, added up over every call to the model. Each call sends the conversation so far again.${cached}`; +} + +/** One line that says what a call was about: the start of its statement, or its arguments. */ +export function callSummary(item: ToolItem, argumentText: string, maxLength = 140): string { + const text = (item.sql ?? argumentText).replace(/\s+/g, ' ').trim(); + return text.length > maxLength ? `${text.slice(0, maxLength - 3).trimEnd()}...` : text; +} diff --git a/src/lib/equivalentSql.test.ts b/src/lib/equivalentSql.test.ts new file mode 100644 index 0000000..3fac5fb --- /dev/null +++ b/src/lib/equivalentSql.test.ts @@ -0,0 +1,72 @@ +import { describe, expect, it } from 'vitest'; +import { equivalentSql } from './equivalentSql'; + +describe('equivalentSql', () => { + it('gives the statement the engine builds for each discovery tool', () => { + expect(equivalentSql('list_providers', {})).toBe('SHOW PROVIDERS;'); + expect(equivalentSql('list_services', { provider: 'github' })).toBe('SHOW SERVICES IN github;'); + expect(equivalentSql('list_resources', { provider: 'github', service: 'repos' })).toBe( + 'SHOW RESOURCES IN github.repos;', + ); + expect( + equivalentSql('list_methods', { provider: 'aws', service: 'ec2', resource: 'instances' }), + ).toBe('SHOW METHODS IN aws.ec2.instances;'); + }); + + it('covers the registry tools, with and without the optional argument', () => { + expect(equivalentSql('list_registry', {})).toBe('REGISTRY LIST;'); + expect(equivalentSql('list_registry', { provider: 'aws' })).toBe('REGISTRY LIST aws;'); + expect(equivalentSql('pull_provider', { provider: 'github' })).toBe('REGISTRY PULL github;'); + expect(equivalentSql('pull_provider', { provider: 'github', version: 'v26.08.00448' })).toBe( + 'REGISTRY PULL github v26.08.00448;', + ); + }); + + it('ignores arguments that only shape the output', () => { + expect( + equivalentSql('list_services', { provider: 'aws', format: 'json', row_limit: 10000 }), + ).toBe('SHOW SERVICES IN aws;'); + expect(equivalentSql('list_providers', { format: 'markdown' })).toBe('SHOW PROVIDERS;'); + }); + + it('gives nothing when an argument it does not know could change the statement', () => { + expect(equivalentSql('list_services', { provider: 'aws', like: 'ec%' })).toBeNull(); + expect(equivalentSql('list_providers', { filter: 'git' })).toBeNull(); + }); + + it('gives nothing when a required name is missing', () => { + expect(equivalentSql('list_services', {})).toBeNull(); + expect(equivalentSql('list_resources', { provider: 'github' })).toBeNull(); + expect(equivalentSql('list_methods', { provider: 'aws', service: 'ec2' })).toBeNull(); + expect(equivalentSql('pull_provider', {})).toBeNull(); + }); + + it('never builds a statement from a name that is not a plain identifier', () => { + expect(equivalentSql('list_services', { provider: 'aws; DROP' })).toBeNull(); + expect(equivalentSql('list_services', { provider: "x' OR '1'='1" })).toBeNull(); + expect(equivalentSql('list_resources', { provider: 'aws', service: 'ec2.x' })).toBeNull(); + expect(equivalentSql('pull_provider', { provider: 'github', version: 'v1; x' })).toBeNull(); + expect(equivalentSql('list_services', { provider: 42 })).toBeNull(); + }); + + it('has nothing for tools with no statement form, or that carry their own SQL', () => { + for (const tool of [ + 'server_info', + 'reload_credentials', + 'query_library_search', + 'query_library_get', + 'describe_method', + 'run_select_query', + 'subagent', + 'made_up', + ]) { + expect(equivalentSql(tool, { provider: 'aws' })).toBeNull(); + } + }); + + it('copes with arguments that are not an object', () => { + expect(equivalentSql('list_providers', null)).toBe('SHOW PROVIDERS;'); + expect(equivalentSql('list_providers', 'text')).toBe('SHOW PROVIDERS;'); + expect(equivalentSql('list_services', ['aws'])).toBeNull(); + }); +}); diff --git a/src/lib/equivalentSql.ts b/src/lib/equivalentSql.ts new file mode 100644 index 0000000..e7c8f26 --- /dev/null +++ b/src/lib/equivalentSql.ts @@ -0,0 +1,79 @@ +// A statement the operator could run to get what a metadata tool returned. +// +// The engine does not say which statement it ran for these tools, so this +// is shown as "Equivalent SQL", never as what ran. The forms are the ones +// the engine itself builds for each tool. A call with an argument this +// file does not know is given no equivalent, since the argument could +// change the statement. + +const IDENTIFIER = /^[A-Za-z0-9_]+$/; +const VERSION = /^[A-Za-z0-9_.-]+$/; + +/** Arguments that shape the tool's output and not the statement. */ +const NEUTRAL = new Set(['format', 'row_limit']); + +function record(args: unknown): Record | null { + return typeof args === 'object' && args !== null && !Array.isArray(args) + ? (args as Record) + : null; +} + +/** True when the call has no argument beyond the named ones. Empty values do not count. */ +function onlyHas(args: Record, allowed: string[]): boolean { + return Object.entries(args).every( + ([key, value]) => + allowed.includes(key) || + NEUTRAL.has(key) || + value === null || + value === '' || + value === false, + ); +} + +function identifier(value: unknown): string | null { + return typeof value === 'string' && IDENTIFIER.test(value) ? value : null; +} + +/** The equivalent statement for a tool call, or null when there is none to give. */ +export function equivalentSql(tool: string, rawArgs: unknown): string | null { + const args = record(rawArgs) ?? {}; + const provider = identifier(args.provider); + const service = identifier(args.service); + const resource = identifier(args.resource); + + switch (tool) { + case 'list_providers': + return onlyHas(args, []) ? 'SHOW PROVIDERS;' : null; + case 'list_services': + return provider && onlyHas(args, ['provider']) ? `SHOW SERVICES IN ${provider};` : null; + case 'list_resources': + return provider && service && onlyHas(args, ['provider', 'service']) + ? `SHOW RESOURCES IN ${provider}.${service};` + : null; + case 'list_methods': + return provider && service && resource && onlyHas(args, ['provider', 'service', 'resource']) + ? `SHOW METHODS IN ${provider}.${service}.${resource};` + : null; + case 'list_registry': + if (!onlyHas(args, ['provider'])) { + return null; + } + if (args.provider === undefined || args.provider === null || args.provider === '') { + return 'REGISTRY LIST;'; + } + return provider ? `REGISTRY LIST ${provider};` : null; + case 'pull_provider': { + if (!provider || !onlyHas(args, ['provider', 'version'])) { + return null; + } + if (args.version === undefined || args.version === null || args.version === '') { + return `REGISTRY PULL ${provider};`; + } + return typeof args.version === 'string' && VERSION.test(args.version) + ? `REGISTRY PULL ${provider} ${args.version};` + : null; + } + default: + return null; + } +} diff --git a/src/lib/explorerTree.test.ts b/src/lib/explorerTree.test.ts new file mode 100644 index 0000000..ea0c433 --- /dev/null +++ b/src/lib/explorerTree.test.ts @@ -0,0 +1,483 @@ +import { describe, expect, it, vi } from 'vitest'; +import { + fieldNodes, + loadChildren, + methodNodes, + compareVersions, + filterRows, + hoverText, + methodGroupNodes, + paramNodes, + parseJump, + unopenedServices, + providerNodes, + qualifiedName, + resourceGroupNodes, + resourceNodes, + serviceNodes, + visibleRows, + type ChildState, + type ExplorerApi, +} from './explorerTree'; + +function api(over: Partial = {}): ExplorerApi { + return { + providers: vi.fn(() => Promise.resolve([])), + services: vi.fn(() => Promise.resolve([])), + resources: vi.fn(() => Promise.resolve([])), + methods: vi.fn(() => Promise.resolve([])), + fields: vi.fn(() => Promise.resolve([])), + methodFields: vi.fn(() => Promise.resolve([])), + ...over, + }; +} + +describe('qualifiedName', () => { + it('joins the parts that are present', () => { + expect(qualifiedName({ provider: 'github' })).toBe('github'); + expect(qualifiedName({ provider: 'github', service: 'repos' })).toBe('github.repos'); + expect(qualifiedName({ provider: 'github', service: 'repos', resource: 'repos' })).toBe( + 'github.repos.repos', + ); + expect( + qualifiedName({ provider: 'github', service: 'repos', resource: 'repos', method: 'get' }), + ).toBe('github.repos.repos.get'); + }); +}); + +describe('nodes', () => { + it('sorts providers and copies the provider name', () => { + const nodes = providerNodes([ + { name: 'homebrew', version: 'v2' }, + { name: 'github', version: 'v1' }, + ]); + expect(nodes.map((n) => n.label)).toEqual(['github', 'homebrew']); + expect(nodes[0]).toMatchObject({ kind: 'provider', detail: 'v1', copyText: 'github' }); + expect(nodes.every((n) => n.expandable)).toBe(true); + }); + + it('copies the fully qualified name for services and resources', () => { + const [service] = serviceNodes('homebrew', [ + { name: 'formula', id: 'formula:v25', title: 'Homebrew Formulae API', description: '' }, + ]); + expect(service).toMatchObject({ + copyText: 'homebrew.formula', + detail: 'Homebrew Formulae API', + }); + + const [resource] = resourceNodes('homebrew', 'formula', [ + { name: 'vw_info', id: 'homebrew.formula.vw_info', description: '' }, + ]); + expect(resource).toMatchObject({ copyText: 'homebrew.formula.vw_info', expandable: true }); + }); + + it('does not repeat a service title that equals its name', () => { + const [service] = serviceNodes('x', [ + { name: 'repos', id: '', title: 'repos', description: '' }, + ]); + expect(service?.detail).toBe(''); + }); + + it('opens a resource into fields and methods', () => { + const groups = resourceGroupNodes({ provider: 'a', service: 'b', resource: 'c' }); + expect(groups.map((g) => g.kind)).toEqual(['fieldsGroup', 'methodsGroup']); + expect(groups.every((g) => g.copyText === null)).toBe(true); + expect(new Set(groups.map((g) => g.id)).size).toBe(2); + }); + + it('keeps fields in column order and copies the bare column name', () => { + const nodes = fieldNodes({ provider: 'a', service: 'b', resource: 'c' }, [ + { name: 'name', type: 'string', description: '' }, + { name: 'aliases', type: 'array', description: '' }, + ]); + expect(nodes.map((n) => n.label)).toEqual(['name', 'aliases']); + expect(nodes[1]).toMatchObject({ copyText: 'aliases', detail: 'array', expandable: false }); + }); + + it('shows the SQL verb on a method and copies its qualified name', () => { + const [method] = methodNodes({ provider: 'github', service: 'repos', resource: 'repos' }, [ + { + name: 'list_for_org', + sqlVerb: 'SELECT', + requiredParams: ['org'], + description: 'repos/list-for-org', + }, + ]); + expect(method).toMatchObject({ + verb: 'SELECT', + detail: '', + copyText: 'github.repos.repos.list_for_org', + expandable: true, + }); + expect(method?.title).toContain('Required: org'); + expect(method?.path.method).toBe('list_for_org'); + }); + + it('orders method parameters: required, optional, then outputs', () => { + const nodes = paramNodes({ provider: 'a', service: 'b', resource: 'c', method: 'm' }, [ + { name: 'out_b', type: 'string', paramType: 'output', shape: '', description: '' }, + { name: 'opt', type: 'string', paramType: 'input_optional', shape: '', description: '' }, + { name: 'req', type: 'string', paramType: 'input_required', shape: '', description: '' }, + { name: 'out_a', type: 'array', paramType: 'output', shape: '', description: '' }, + ]); + expect(nodes.map((n) => n.label)).toEqual(['req', 'opt', 'out_b', 'out_a']); + // An output shows only its type. The group it sits in says it is one. + expect(nodes.map((n) => n.detail)).toEqual([ + 'required string', + 'optional string', + 'string', + 'array', + ]); + }); + + it('splits a method into an Inputs group and an Outputs group', () => { + const path = { provider: 'a', service: 'b', resource: 'c', method: 'm' }; + const [inputs, outputs] = methodGroupNodes(path, [ + { name: 'out_b', type: 'string', paramType: 'output', shape: '', description: '' }, + { name: 'opt', type: 'string', paramType: 'input_optional', shape: '', description: '' }, + { name: 'req', type: 'string', paramType: 'input_required', shape: '', description: '' }, + { name: 'out_a', type: 'array', paramType: 'output', shape: '', description: '' }, + ]); + expect(inputs).toMatchObject({ + kind: 'inputsGroup', + label: 'Inputs', + detail: '2, 1 required', + expandable: true, + copyText: null, + }); + expect(inputs?.children?.map((n) => n.label)).toEqual(['req', 'opt']); + expect(outputs).toMatchObject({ + kind: 'outputsGroup', + label: 'Outputs', + detail: '2', + expandable: true, + }); + expect(outputs?.children?.map((n) => n.label)).toEqual(['out_b', 'out_a']); + expect(inputs?.id).not.toBe(outputs?.id); + }); + + it('counts a field the engine calls a response as an output', () => { + // The provider built into the engine marks what a method returns as + // `response`, where the others say `output`. + const path = { provider: 'a', service: 'b', resource: 'c', method: 'm' }; + const [inputs, outputs] = methodGroupNodes(path, [ + { name: 'vpc_id', type: 'string', paramType: 'response', shape: '', description: '' }, + { name: 'region', type: 'string', paramType: 'input_optional', shape: '', description: '' }, + { name: 'cidr', type: 'string', paramType: 'response', shape: '', description: '' }, + ]); + expect(inputs?.children?.map((n) => n.label)).toEqual(['region']); + expect(inputs?.detail).toBe('1, 0 required'); + expect(outputs?.children?.map((n) => n.label)).toEqual(['vpc_id', 'cidr']); + expect(outputs?.children?.map((n) => n.detail)).toEqual(['string', 'string']); + }); + + it('shows an empty group as one that cannot be opened', () => { + const path = { provider: 'a', service: 'b', resource: 'c', method: 'm' }; + const [inputs, outputs] = methodGroupNodes(path, [ + { name: 'req', type: 'string', paramType: 'input_required', shape: '', description: '' }, + ]); + expect(inputs).toMatchObject({ detail: '1, 1 required', expandable: true }); + expect(outputs).toMatchObject({ detail: 'none', expandable: false }); + expect(outputs?.children).toEqual([]); + }); + + it('gives the same parameter name distinct ids as input and output', () => { + const nodes = paramNodes({ provider: 'a', service: 'b', resource: 'c', method: 'm' }, [ + { name: 'x', type: '', paramType: 'input_required', shape: '', description: '' }, + { name: 'x', type: '', paramType: 'output', shape: '', description: '' }, + ]); + expect(new Set(nodes.map((n) => n.id)).size).toBe(2); + }); +}); + +describe('loadChildren', () => { + it('loads providers for the root', async () => { + const explorer = api({ + providers: vi.fn(() => Promise.resolve([{ name: 'github', version: 'v1' }])), + }); + const nodes = await loadChildren(null, explorer); + expect(nodes.map((n) => n.label)).toEqual(['github']); + }); + + it('asks the host with the names on the path', async () => { + const explorer = api(); + const [provider] = providerNodes([{ name: 'github', version: 'v1' }]); + const [service] = serviceNodes('github', [ + { name: 'repos', id: '', title: '', description: '' }, + ]); + const [resource] = resourceNodes('github', 'repos', [ + { name: 'repos', id: '', description: '' }, + ]); + if (!provider || !service || !resource) { + throw new Error('fixtures missing'); + } + + await loadChildren(provider, explorer); + expect(explorer.services).toHaveBeenCalledWith('github'); + + await loadChildren(service, explorer); + expect(explorer.resources).toHaveBeenCalledWith('github', 'repos'); + + // A resource opens into its two groups without a host call. + const groups = await loadChildren(resource, explorer); + expect(groups).toHaveLength(2); + expect(explorer.fields).not.toHaveBeenCalled(); + + const [fieldsGroup, methodsGroup] = groups; + if (!fieldsGroup || !methodsGroup) { + throw new Error('groups missing'); + } + await loadChildren(fieldsGroup, explorer); + expect(explorer.fields).toHaveBeenCalledWith('github', 'repos', 'repos'); + await loadChildren(methodsGroup, explorer); + expect(explorer.methods).toHaveBeenCalledWith('github', 'repos', 'repos'); + }); + + it('loads method parameters with all four names', async () => { + const explorer = api(); + const [method] = methodNodes({ provider: 'p', service: 's', resource: 'r' }, [ + { name: 'get', sqlVerb: 'SELECT', requiredParams: [], description: '' }, + ]); + if (!method) { + throw new Error('fixture missing'); + } + const groups = await loadChildren(method, explorer); + expect(explorer.methodFields).toHaveBeenCalledWith('p', 's', 'r', 'get'); + expect(groups.map((n) => n.kind)).toEqual(['inputsGroup', 'outputsGroup']); + }); + + it('opens a method group from the fields it already holds', async () => { + const explorer = api({ + methodFields: vi.fn(() => + Promise.resolve([ + { name: 'org', type: 'string', paramType: 'input_required', shape: '', description: '' }, + { name: 'id', type: 'integer', paramType: 'output', shape: '', description: '' }, + ]), + ), + }); + const [method] = methodNodes({ provider: 'p', service: 's', resource: 'r' }, [ + { name: 'get', sqlVerb: 'SELECT', requiredParams: ['org'], description: '' }, + ]); + if (!method) { + throw new Error('fixture missing'); + } + const [inputs, outputs] = await loadChildren(method, explorer); + if (!inputs || !outputs) { + throw new Error('groups missing'); + } + expect((await loadChildren(inputs, explorer)).map((n) => n.label)).toEqual(['org']); + expect((await loadChildren(outputs, explorer)).map((n) => n.label)).toEqual(['id']); + expect(explorer.methodFields).toHaveBeenCalledTimes(1); + }); + + it('has nothing under a field', async () => { + const [field] = fieldNodes({ provider: 'p', service: 's', resource: 'r' }, [ + { name: 'x', type: '', description: '' }, + ]); + if (!field) { + throw new Error('fixture missing'); + } + expect(await loadChildren(field, api())).toEqual([]); + }); +}); + +describe('visibleRows', () => { + const roots = providerNodes([ + { name: 'github', version: 'v1' }, + { name: 'homebrew', version: 'v2' }, + ]); + const services = serviceNodes('github', [{ name: 'repos', id: '', title: '', description: '' }]); + + it('shows only roots when nothing is expanded', () => { + const rows = visibleRows(roots, new Set(), new Map()); + expect(rows.map((r) => [r.node.label, r.depth])).toEqual([ + ['github', 0], + ['homebrew', 0], + ]); + }); + + it('shows loaded children under an expanded node, one level deeper', () => { + const children = new Map([ + ['p:github', { status: 'loaded', nodes: services }], + ]); + const rows = visibleRows(roots, new Set(['p:github']), children); + expect(rows.map((r) => [r.node.label, r.depth])).toEqual([ + ['github', 0], + ['repos', 1], + ['homebrew', 0], + ]); + }); + + it('hides children of a collapsed node even when they are loaded', () => { + const children = new Map([ + ['p:github', { status: 'loaded', nodes: services }], + ]); + expect(visibleRows(roots, new Set(), children)).toHaveLength(2); + }); + + it('carries the loading and error state on the expanded row', () => { + const loading = visibleRows( + roots, + new Set(['p:github']), + new Map([['p:github', { status: 'loading' }]]), + ); + expect(loading[0]?.state).toEqual({ status: 'loading' }); + + const failed = visibleRows( + roots, + new Set(['p:github']), + new Map([['p:github', { status: 'error', message: 'nope' }]]), + ); + expect(failed[0]?.state).toEqual({ status: 'error', message: 'nope' }); + expect(failed).toHaveLength(2); + }); +}); + +describe('filterRows', () => { + const roots = providerNodes([ + { name: 'aws', version: 'v1' }, + { name: 'github', version: 'v2' }, + ]); + const [aws, github] = roots; + const awsServices = serviceNodes('aws', [ + { name: 'ec2', id: '', title: '', description: '' }, + { name: 's3', id: '', title: '', description: '' }, + ]); + const githubServices = serviceNodes('github', [ + { name: 'repos', id: '', title: '', description: '' }, + ]); + const reposResources = resourceNodes('github', 'repos', [ + { name: 'repos', id: '', description: '' }, + { name: 'branches', id: '', description: '' }, + ]); + const loaded = (nodes: ReturnType) => ({ + status: 'loaded' as const, + nodes, + }); + if (!aws || !github || !githubServices[0]) { + throw new Error('fixtures missing'); + } + const children = new Map([ + [aws.id, loaded(awsServices)], + [github.id, loaded(githubServices)], + [githubServices[0].id, loaded(reposResources)], + ]); + const labels = (query: string, expanded = new Set()) => + filterRows(roots, expanded, children, query).map((row) => `${row.depth}:${row.node.label}`); + + it('is the plain tree when the filter is empty', () => { + expect(labels('')).toEqual(['0:aws', '0:github']); + expect(labels(' ')).toEqual(['0:aws', '0:github']); + }); + + it('keeps the parents of a match in view, opened', () => { + expect(labels('branch')).toEqual(['0:github', '1:repos', '2:branches']); + const rows = filterRows(roots, new Set(), children, 'branch'); + expect(rows.map((row) => row.expanded)).toEqual([true, true, false]); + expect(rows.map((row) => row.matched)).toEqual([false, false, true]); + }); + + it('matches part of a name at any level, without regard to case', () => { + expect(labels('EC')).toEqual(['0:aws', '1:ec2']); + expect(labels('git')).toEqual(['0:github']); + // The service and the resource of the same name both match. + expect(labels('repo')).toEqual(['0:github', '1:repos', '2:repos']); + }); + + it('shows nothing when nothing loaded matches', () => { + expect(labels('lambda')).toEqual([]); + }); + + it('lets a node that matched by name be opened to show all it has', () => { + expect(labels('git', new Set([github.id]))).toEqual(['0:github', '1:repos']); + }); + + it('does not match on the Fields and Methods groups', () => { + const [resource] = reposResources; + if (!resource) { + throw new Error('fixture missing'); + } + const withGroups = new Map(children).set(resource.id, { + status: 'loaded' as const, + nodes: resourceGroupNodes(resource.path), + }); + const rows = filterRows(roots, new Set(), withGroups, 'methods'); + expect(rows).toEqual([]); + }); + + it('counts the services whose resources are not loaded yet', () => { + expect(unopenedServices(roots, children).map((node) => node.label)).toEqual(['ec2', 's3']); + // A provider whose services are not loaded contributes none. + expect(unopenedServices(roots, new Map())).toEqual([]); + }); +}); + +describe('parseJump', () => { + it('reads one to three dotted names', () => { + expect(parseJump('github')).toEqual({ provider: 'github' }); + expect(parseJump('github.repos')).toEqual({ provider: 'github', service: 'repos' }); + expect(parseJump(' aws.ec2.instances; ')).toEqual({ + provider: 'aws', + service: 'ec2', + resource: 'instances', + }); + expect(parseJump('"aws"."ec2"."instances"')).toEqual({ + provider: 'aws', + service: 'ec2', + resource: 'instances', + }); + }); + + it('refuses anything else', () => { + for (const bad of ['', '.', 'aws.', '.ec2', 'a..b', 'a.b.c.d']) { + expect(parseJump(bad)).toBeNull(); + } + }); +}); + +describe('compareVersions', () => { + it('orders versions by their numbers, not as text', () => { + expect(compareVersions('v26.08.00444', 'v26.09.00461')).toBeLessThan(0); + expect(compareVersions('v26.09.00461', 'v26.08.00444')).toBeGreaterThan(0); + expect(compareVersions('v26.08.00444', 'v26.08.00444')).toBe(0); + expect(compareVersions('v9.1.5', 'v10.0.0')).toBeLessThan(0); + expect(compareVersions('26.08.444', 'v26.08.00444')).toBe(0); + }); + + it('claims nothing about a version it cannot read', () => { + expect(compareVersions('internal', 'v1.0.0')).toBeNull(); + expect(compareVersions('v1.0', 'v1.0.0')).toBeNull(); + expect(compareVersions('', '')).toBeNull(); + }); +}); + +describe('hoverText', () => { + it('leads with the whole name, then what the engine says', () => { + const [service] = serviceNodes('github', [ + { name: 'repos', id: 'repos:v1', title: 'repos API', description: 'Repositories.' }, + ]); + expect(service && hoverText(service)).toBe('github.repos\nRepositories.'); + const [resource] = resourceNodes('github', 'repos', [ + { name: 'repos', id: 'github.repos.repos', description: '' }, + ]); + expect(resource && hoverText(resource)).toBe('github.repos.repos'); + }); + + it('names the verb of a method', () => { + const [method] = methodNodes({ provider: 'github', service: 'repos', resource: 'repos' }, [ + { name: 'list_for_org', sqlVerb: 'select', requiredParams: ['org'], description: '' }, + ]); + expect(method && hoverText(method)).toBe( + 'SELECT github.repos.repos.list_for_org\nRequired: org', + ); + }); + + it('gives a provider its version and a field its type', () => { + const [provider] = providerNodes([{ name: 'github', version: 'v26.08.00448' }]); + expect(provider && hoverText(provider)).toBe('github v26.08.00448'); + const [field] = fieldNodes({ provider: 'github', service: 'repos', resource: 'repos' }, [ + { name: 'stargazers_count', type: 'integer', description: 'Stars.' }, + ]); + expect(field && hoverText(field)).toBe('stargazers_count integer\nStars.'); + }); +}); diff --git a/src/lib/explorerTree.ts b/src/lib/explorerTree.ts new file mode 100644 index 0000000..e553bea --- /dev/null +++ b/src/lib/explorerTree.ts @@ -0,0 +1,479 @@ +// The explorer tree: node shapes, how children are loaded, and what "copy +// name" copies. Kept free of React and of Tauri so it can be tested. + +import type { Field, Method, MethodField, Provider, Resource, Service } from '../host/types'; + +export type NodeKind = + | 'provider' + | 'service' + | 'resource' + | 'fieldsGroup' + | 'methodsGroup' + | 'field' + | 'method' + | 'inputsGroup' + | 'outputsGroup' + | 'param'; + +export interface NodePath { + provider: string; + service?: string; + resource?: string; + method?: string; +} + +export interface TreeNode { + /** Unique within the tree. */ + id: string; + kind: NodeKind; + label: string; + /** Secondary text shown dimmed after the label: a version, a type, a verb. */ + detail: string; + /** Tooltip. */ + title: string; + /** What the copy action puts on the clipboard. Null when there is nothing sensible. */ + copyText: string | null; + expandable: boolean; + path: NodePath; + /** Children already in hand, for a group whose members arrived with its parent. */ + children?: TreeNode[]; + /** For a method: its SQL verb, in capitals. */ + verb?: string; +} + +/** The slice of the host API the tree needs. */ +export interface ExplorerApi { + providers(): Promise; + services(provider: string): Promise; + resources(provider: string, service: string): Promise; + methods(provider: string, service: string, resource: string): Promise; + fields(provider: string, service: string, resource: string): Promise; + methodFields( + provider: string, + service: string, + resource: string, + method: string, + ): Promise; +} + +/** The dotted name of a provider, service, resource or method. */ +export function qualifiedName(path: NodePath): string { + return [path.provider, path.service, path.resource, path.method] + .filter((part): part is string => part !== undefined) + .join('.'); +} + +/** + * What a row shows on hover: the whole name first, because the row may be + * cut short, then what the engine says about it. + */ +export function hoverText(node: TreeNode): string { + const named = + node.kind === 'field' || node.kind === 'param' + ? [node.label, node.detail].filter(Boolean).join(' ') + : [node.verb, node.copyText ?? node.label, node.kind === 'provider' ? node.detail : ''] + .filter(Boolean) + .join(' '); + const about = node.kind === 'provider' ? '' : node.title; + return about !== '' && about !== named && about !== node.copyText ? `${named}\n${about}` : named; +} + +const byName = (a: T, b: T) => a.name.localeCompare(b.name); + +export function providerNodes(providers: Provider[]): TreeNode[] { + return [...providers].sort(byName).map((provider) => ({ + id: `p:${provider.name}`, + kind: 'provider', + label: provider.name, + detail: provider.version, + title: `Provider ${provider.name} ${provider.version}`.trim(), + copyText: provider.name, + expandable: true, + path: { provider: provider.name }, + })); +} + +export function serviceNodes(provider: string, services: Service[]): TreeNode[] { + return [...services].sort(byName).map((service) => { + const path = { provider, service: service.name }; + // A title that only repeats the name, such as "ec2 API", says nothing. + const title = service.title.trim().toLowerCase(); + const name = service.name.toLowerCase(); + const repeats = title === name || title === `${name} api`; + return { + id: `s:${qualifiedName(path)}`, + kind: 'service', + label: service.name, + detail: repeats ? '' : service.title, + title: service.description || service.title || qualifiedName(path), + copyText: qualifiedName(path), + expandable: true, + path, + }; + }); +} + +export function resourceNodes( + provider: string, + service: string, + resources: Resource[], +): TreeNode[] { + return [...resources].sort(byName).map((resource) => { + const path = { provider, service, resource: resource.name }; + return { + id: `r:${qualifiedName(path)}`, + kind: 'resource', + label: resource.name, + detail: '', + title: resource.description || qualifiedName(path), + copyText: qualifiedName(path), + expandable: true, + path, + }; + }); +} + +/** A resource opens into two groups, so fields and methods load separately. */ +export function resourceGroupNodes(path: NodePath): TreeNode[] { + const name = qualifiedName(path); + return [ + { + id: `fg:${name}`, + kind: 'fieldsGroup', + label: 'Fields', + detail: '', + title: `Columns of ${name}`, + copyText: null, + expandable: true, + path, + }, + { + id: `mg:${name}`, + kind: 'methodsGroup', + label: 'Methods', + detail: '', + title: `Methods of ${name}`, + copyText: null, + expandable: true, + path, + }, + ]; +} + +export function fieldNodes(path: NodePath, fields: Field[]): TreeNode[] { + const name = qualifiedName(path); + // Keep the engine's order. It is the order of the columns. + return fields.map((field) => ({ + id: `f:${name}:${field.name}`, + kind: 'field', + label: field.name, + detail: field.type, + title: field.description || `${name}.${field.name}`, + // A column name is what a statement needs, not a dotted path. + copyText: field.name, + expandable: false, + path, + })); +} + +export function methodNodes(path: NodePath, methods: Method[]): TreeNode[] { + return [...methods].sort(byName).map((method) => { + const methodPath = { ...path, method: method.name }; + const params = method.requiredParams.length + ? `Required: ${method.requiredParams.join(', ')}` + : 'No required parameters'; + return { + id: `m:${qualifiedName(methodPath)}`, + kind: 'method', + label: method.name, + // The verb is drawn as a pill before the name, not as trailing text. + detail: '', + verb: method.sqlVerb.toUpperCase(), + title: [method.description, params].filter(Boolean).join('\n'), + copyText: qualifiedName(methodPath), + expandable: true, + path: methodPath, + }; + }); +} + +const PARAM_ORDER: Record = { input_required: 0, input_optional: 1, output: 2 }; +const PARAM_LABEL: Record = { + input_required: 'required', + input_optional: 'optional', + output: 'output', +}; + +/** + * Whether a field is something a statement supplies. The engine marks those + * `input_required` or `input_optional`. What it returns is marked `output` + * by most providers and `response` by the built-in one, so anything that + * is not an input counts as an output. + */ +const isInput = (field: MethodField) => field.paramType.startsWith('input'); +const isOutput = (field: MethodField) => !isInput(field); + +/** + * The nodes for a method's fields: required inputs, optional inputs, then + * outputs, each kind in the engine's order. An output shows only its type, + * because it sits in the Outputs group. + */ +export function paramNodes(path: NodePath, fields: MethodField[]): TreeNode[] { + const name = qualifiedName(path); + const rank = (field: MethodField) => PARAM_ORDER[field.paramType] ?? 2; + return fields + .map((field, position) => ({ field, position })) + .sort((a, b) => rank(a.field) - rank(b.field) || a.position - b.position) + .map(({ field }) => { + const role = PARAM_LABEL[field.paramType] ?? field.paramType; + return { + id: `mp:${name}:${field.paramType}:${field.name}`, + kind: 'param' as const, + label: field.name, + detail: [isOutput(field) ? '' : role, field.type].filter(Boolean).join(' '), + title: field.description || `${field.name} (${role})`, + copyText: field.name, + expandable: false, + path, + }; + }); +} + +/** + * A method opens into two groups, Inputs and Outputs, so what a statement + * must supply is kept apart from what it returns. Both start collapsed. The + * fields arrive in one answer from the engine, so each group carries its + * members and opening it needs no second request. + */ +export function methodGroupNodes(path: NodePath, fields: MethodField[]): TreeNode[] { + const name = qualifiedName(path); + const inputs = fields.filter(isInput); + const outputs = fields.filter(isOutput); + const required = inputs.filter((field) => field.paramType === 'input_required').length; + return [ + { + id: `ig:${name}`, + kind: 'inputsGroup', + label: 'Inputs', + detail: inputs.length === 0 ? 'none' : `${inputs.length}, ${required} required`, + title: `What ${name} takes: WHERE clause parameters and request fields`, + copyText: null, + expandable: inputs.length > 0, + path, + children: paramNodes(path, inputs), + }, + { + id: `og:${name}`, + kind: 'outputsGroup', + label: 'Outputs', + detail: outputs.length === 0 ? 'none' : String(outputs.length), + title: `What ${name} returns: the columns a statement can select`, + copyText: null, + expandable: outputs.length > 0, + path, + children: paramNodes(path, outputs), + }, + ]; +} + +/** Loads the children of a node. `null` loads the roots. */ +export async function loadChildren(node: TreeNode | null, api: ExplorerApi): Promise { + if (node === null) { + return providerNodes(await api.providers()); + } + const { provider, service, resource, method } = node.path; + switch (node.kind) { + case 'provider': + return serviceNodes(provider, await api.services(provider)); + case 'service': + if (service === undefined) { + return []; + } + return resourceNodes(provider, service, await api.resources(provider, service)); + case 'resource': + return resourceGroupNodes(node.path); + case 'fieldsGroup': + if (service === undefined || resource === undefined) { + return []; + } + return fieldNodes(node.path, await api.fields(provider, service, resource)); + case 'methodsGroup': + if (service === undefined || resource === undefined) { + return []; + } + return methodNodes(node.path, await api.methods(provider, service, resource)); + case 'method': + if (service === undefined || resource === undefined || method === undefined) { + return []; + } + return methodGroupNodes( + node.path, + await api.methodFields(provider, service, resource, method), + ); + case 'inputsGroup': + case 'outputsGroup': + return node.children ?? []; + case 'field': + case 'param': + return []; + } +} + +export type ChildState = + | { status: 'loading' } + | { status: 'loaded'; nodes: TreeNode[] } + | { status: 'error'; message: string }; + +export interface VisibleRow { + node: TreeNode; + depth: number; + expanded: boolean; + /** Set on the row of an expanded node whose children are loading or failed. */ + state: ChildState | undefined; + /** Under a filter: this node's own name matched. */ + matched?: boolean; +} + +/** Flattens the expanded part of the tree into the rows to draw, top to bottom. */ +export function visibleRows( + roots: TreeNode[], + expanded: ReadonlySet, + children: ReadonlyMap, +): VisibleRow[] { + const rows: VisibleRow[] = []; + const walk = (nodes: TreeNode[], depth: number) => { + for (const node of nodes) { + const isExpanded = expanded.has(node.id); + const state = isExpanded ? children.get(node.id) : undefined; + rows.push({ node, depth, expanded: isExpanded, state }); + if (state?.status === 'loaded') { + walk(state.nodes, depth + 1); + } + } + }; + walk(roots, 0); + return rows; +} + +/** The kinds of node a filter looks at. Groups, fields and parameters are not searched. */ +const SEARCHED: ReadonlySet = new Set(['provider', 'service', 'resource', 'method']); + +/** + * The rows to draw under a filter. A node is shown when its own name holds + * the text, or when something loaded beneath it does. A node with a match + * beneath it is drawn open, so matches keep their parents in view. A node + * that matched by its own name shows its children only when the operator + * opened it. + * + * Only what has been loaded is looked at. Nothing is fetched here. + */ +export function filterRows( + roots: TreeNode[], + expanded: ReadonlySet, + children: ReadonlyMap, + query: string, +): VisibleRow[] { + const text = query.trim().toLowerCase(); + if (text === '') { + return visibleRows(roots, expanded, children); + } + const visit = (node: TreeNode, depth: number): VisibleRow[] => { + const state = children.get(node.id); + const kids = state?.status === 'loaded' ? state.nodes : []; + const below = kids.flatMap((kid) => visit(kid, depth + 1)); + const matched = SEARCHED.has(node.kind) && node.label.toLowerCase().includes(text); + if (!matched && below.length === 0) { + return []; + } + const opened = expanded.has(node.id); + const row: VisibleRow = { + node, + depth, + expanded: below.length > 0 || opened, + state: below.length > 0 || opened ? state : undefined, + matched, + }; + if (below.length > 0) { + return [row, ...below]; + } + // Matched by name, nothing matching beneath: opened by hand, it shows + // everything it has. + if (opened && state?.status === 'loaded') { + const all: VisibleRow[] = []; + const walk = (nodes: TreeNode[], at: number) => { + for (const kid of nodes) { + const kidState = expanded.has(kid.id) ? children.get(kid.id) : undefined; + all.push({ node: kid, depth: at, expanded: expanded.has(kid.id), state: kidState }); + if (kidState?.status === 'loaded') { + walk(kidState.nodes, at + 1); + } + } + }; + walk(kids, depth + 1); + return [row, ...all]; + } + return [row]; + }; + return roots.flatMap((root) => visit(root, 0)); +} + +/** The services whose resources have not been loaded, across loaded providers. */ +export function unopenedServices( + roots: TreeNode[], + children: ReadonlyMap, +): TreeNode[] { + return roots.flatMap((root) => { + const state = children.get(root.id); + const services = state?.status === 'loaded' ? state.nodes : []; + return services.filter((service) => !children.has(service.id)); + }); +} + +/** + * Reads `provider`, `provider.service` or `provider.service.resource` as + * typed into the jump box. A part may be in double quotes. Null when the + * text is not one to three names. + */ +export function parseJump(text: string): NodePath | null { + const parts = text + .trim() + .replace(/;$/, '') + .split('.') + .map((part) => part.trim().replace(/^"(.*)"$/, '$1')); + if (parts.length < 1 || parts.length > 3 || parts.some((part) => part === '')) { + return null; + } + const [provider, service, resource] = parts; + if (provider === undefined) { + return null; + } + return { + provider, + ...(service !== undefined ? { service } : {}), + ...(resource !== undefined ? { resource } : {}), + }; +} + +/** + * Compares two provider versions of the form `v26.08.00444`. Negative when + * `a` is older, positive when newer, zero when the same. Null when either + * is not of that form, in which case nothing is claimed about them. + */ +export function compareVersions(a: string, b: string): number | null { + const parse = (value: string) => { + const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(value.trim()); + return match ? match.slice(1).map(Number) : null; + }; + const left = parse(a); + const right = parse(b); + if (!left || !right) { + return null; + } + for (let i = 0; i < 3; i += 1) { + const difference = (left[i] ?? 0) - (right[i] ?? 0); + if (difference !== 0) { + return difference; + } + } + return 0; +} diff --git a/src/lib/exportResult.test.ts b/src/lib/exportResult.test.ts new file mode 100644 index 0000000..8b7362c --- /dev/null +++ b/src/lib/exportResult.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, it } from 'vitest'; +import { exportFileName, toCsv, toJson, toMarkdownTable, uniqueKeys } from './exportResult'; + +describe('toCsv', () => { + it('writes a header and one record for each row, ended by CRLF', () => { + expect( + toCsv( + ['name', 'stars'], + [ + ['stackql', '512'], + ['docs', '3'], + ], + ), + ).toBe('name,stars\r\nstackql,512\r\ndocs,3\r\n'); + }); + + it('quotes a field that holds a comma, a quote or a line break', () => { + expect(toCsv(['a'], [['x,y'], ['say "hi"'], ['two\nlines']])).toBe( + 'a\r\n"x,y"\r\n"say ""hi"""\r\n"two\nlines"\r\n', + ); + }); + + it('leaves a NULL empty and writes only the header when there are no rows', () => { + expect(toCsv(['a', 'b'], [[null, 'x']])).toBe('a,b\r\n,x\r\n'); + expect(toCsv(['a', 'b'], [])).toBe('a,b\r\n'); + }); +}); + +describe('toJson', () => { + it('writes one object for each row', () => { + expect(JSON.parse(toJson(['name', 'stars'], [['stackql', '512']]))).toEqual([ + { name: 'stackql', stars: '512' }, + ]); + }); + + it('nests objects and arrays, and leaves other values as the text the engine sent', () => { + const [record] = JSON.parse( + toJson( + ['owner', 'topics', 'count', 'flag', 'broken', 'nothing'], + [['{"login":"stackql"}', '["sql","cloud"]', '42', 'true', '{not json}', null]], + ), + ) as Record[]; + expect(record).toEqual({ + owner: { login: 'stackql' }, + topics: ['sql', 'cloud'], + count: '42', + flag: 'true', + broken: '{not json}', + nothing: null, + }); + }); + + it('keeps every column when two share a name', () => { + expect(uniqueKeys(['id', 'name', 'id', 'id'])).toEqual(['id', 'name', 'id_2', 'id_3']); + expect(JSON.parse(toJson(['id', 'id'], [['1', '2']]))).toEqual([{ id: '1', id_2: '2' }]); + }); + + it('writes an empty array for no rows', () => { + expect(toJson(['a'], [])).toBe('[]\n'); + }); +}); + +describe('toMarkdownTable', () => { + it('writes a header, a rule and the rows', () => { + expect(toMarkdownTable(['name', 'stars'], [['stackql', '512']])).toBe( + '| name | stars |\n| --- | --- |\n| stackql | 512 |\n', + ); + }); + + it('keeps a cell on one line and escapes what would break the table', () => { + expect(toMarkdownTable(['v'], [['a|b'], ['two\r\nlines'], [null], ['back\\slash']])).toBe( + '| v |\n| --- |\n| a\\|b |\n| two lines |\n| |\n| back\\\\slash |\n', + ); + }); +}); + +describe('exportFileName', () => { + it('carries the local date and time', () => { + expect(exportFileName('csv', new Date(2026, 10, 18, 9, 5, 7))).toBe( + 'stackql-result-20261118-090507.csv', + ); + }); +}); diff --git a/src/lib/exportResult.ts b/src/lib/exportResult.ts new file mode 100644 index 0000000..cc2b13e --- /dev/null +++ b/src/lib/exportResult.ts @@ -0,0 +1,90 @@ +// A result set as CSV, JSON or a Markdown table. Pure text in, text out. +// The host saves the text. Nothing here touches a file. + +import type { Row } from '../host/types'; +import { looksLikeJson } from './cell'; + +const CSV_SPECIAL = /[",\r\n]/; + +function csvField(value: string | null): string { + if (value === null) { + return ''; + } + return CSV_SPECIAL.test(value) ? `"${value.replace(/"/g, '""')}"` : value; +} + +/** RFC 4180: CRLF between records, quotes doubled. A NULL is an empty field. */ +export function toCsv(columns: string[], rows: Row[]): string { + return `${[columns, ...rows].map((record) => record.map(csvField).join(',')).join('\r\n')}\r\n`; +} + +/** Column names made unique, so an object can hold every column. */ +export function uniqueKeys(columns: string[]): string[] { + const seen = new Map(); + return columns.map((column) => { + const count = (seen.get(column) ?? 0) + 1; + seen.set(column, count); + return count === 1 ? column : `${column}_${count}`; + }); +} + +/** + * The engine sends every value as text. An object or an array is put in + * the file as JSON, because its shape is unambiguous. Anything else stays + * the text the engine sent: a number is not guessed from its digits. + */ +function jsonValue(value: string | null): unknown { + if (value === null) { + return null; + } + const trimmed = value.trim(); + if (looksLikeJson(trimmed)) { + try { + const parsed: unknown = JSON.parse(trimmed); + if (typeof parsed === 'object' && parsed !== null) { + return parsed; + } + } catch { + // Not JSON after all. + } + } + return value; +} + +/** An array with one object for each row, keyed by column name. */ +export function toJson(columns: string[], rows: Row[]): string { + const keys = uniqueKeys(columns); + const records = rows.map((row) => + Object.fromEntries(keys.map((key, index) => [key, jsonValue(row[index] ?? null)])), + ); + return `${JSON.stringify(records, null, 2)}\n`; +} + +function markdownCell(value: string | null): string { + if (value === null) { + return ''; + } + return value + .replace(/\\/g, '\\\\') + .replace(/\|/g, '\\|') + .replace(/\r?\n|\r/g, ' '); +} + +/** A Markdown table. A cell is kept on one line and its pipes are escaped. */ +export function toMarkdownTable(columns: string[], rows: Row[]): string { + const line = (cells: string[]) => `| ${cells.join(' | ')} |`; + return `${[ + line(columns.map(markdownCell)), + line(columns.map(() => '---')), + ...rows.map((row) => line(columns.map((_, index) => markdownCell(row[index] ?? null)))), + ].join('\n')}\n`; +} + +const two = (value: number) => String(value).padStart(2, '0'); + +/** The name a saved result is offered under, for example stackql-result-20261118-174500.csv. */ +export function exportFileName(extension: string, now: Date): string { + const day = `${now.getFullYear()}${two(now.getMonth() + 1)}${two(now.getDate())}`; + const time = `${two(now.getHours())}${two(now.getMinutes())}${two(now.getSeconds())}`; + return `stackql-result-${day}-${time}.${extension}`; +} diff --git a/src/lib/generateSql.test.ts b/src/lib/generateSql.test.ts new file mode 100644 index 0000000..df3e719 --- /dev/null +++ b/src/lib/generateSql.test.ts @@ -0,0 +1,204 @@ +import { describe, expect, it } from 'vitest'; +import type { Method, MethodField } from '../host/types'; +import { + generateStatement, + ident, + otherSelectMethods, + pickSelectMethod, + tableName, +} from './generateSql'; + +const path = { provider: 'github', service: 'repos', resource: 'repos' }; +const field = (name: string, paramType: string, type = 'string'): MethodField => ({ + name, + type, + paramType, + shape: '', + description: '', +}); +const method = (name: string, sqlVerb: string, requiredParams: string[]): Method => ({ + name, + sqlVerb, + requiredParams, + description: '', +}); + +describe('names', () => { + it('leaves plain names bare and quotes the rest', () => { + expect(ident('repos')).toBe('repos'); + expect(ident('list')).toBe('list'); + expect(ident('my-thing')).toBe('"my-thing"'); + expect(ident('odd"name')).toBe('"odd""name"'); + expect(ident('1st')).toBe('"1st"'); + }); + + it('writes the dotted table name', () => { + expect(tableName(path)).toBe('github.repos.repos'); + expect(tableName({ provider: 'a', service: 'b-c', resource: 'd' })).toBe('a."b-c".d'); + }); +}); + +describe('pickSelectMethod', () => { + it('takes the SELECT method that needs the fewest parameters', () => { + const picked = pickSelectMethod([ + method('get', 'SELECT', ['owner', 'repo']), + method('delete', 'DELETE', []), + method('list_for_org', 'SELECT', ['org']), + method('list_for_user', 'select', ['username']), + ]); + expect(picked?.name).toBe('list_for_org'); + }); + + it('has nothing to pick when no method is a SELECT', () => { + expect(pickSelectMethod([method('delete', 'DELETE', ['id'])])).toBeNull(); + expect(pickSelectMethod([])).toBeNull(); + }); +}); + +describe('otherSelectMethods', () => { + const methods = [ + method('list_public', 'SELECT', []), + method('list_for_org', 'SELECT', ['org']), + method('get', 'select', ['owner', 'repo']), + method('delete', 'DELETE', ['owner', 'repo']), + ]; + + it('names the SELECT methods that were not picked, with what each requires', () => { + const picked = methods[0]; + expect(picked && otherSelectMethods(methods, picked)).toBe( + '-- Other SELECT methods, with what each requires: list_for_org (org); get (owner, repo).', + ); + }); + + it('says nothing when the picked method is the only SELECT', () => { + const only = method('list', 'SELECT', []); + expect(otherSelectMethods([only, method('delete', 'DELETE', [])], only)).toBe(''); + }); +}); + +describe('generateStatement', () => { + const fields = [ + field('org', 'input_required'), + field('per_page', 'input_optional', 'integer'), + field('name', 'output'), + field('stargazers_count', 'output', 'integer'), + ]; + + it('lists the output fields and puts required parameters in WHERE', () => { + expect(generateStatement(path, 'SELECT', 'list_for_org', fields)).toBe( + [ + '-- github.repos.repos, method list_for_org (SELECT). Fill in each before running.', + 'SELECT', + ' name,', + ' stargazers_count', + 'FROM github.repos.repos', + "WHERE org = '';", + '', + ].join('\n'), + ); + }); + + it('joins several required parameters with AND and leaves numbers unquoted', () => { + const sql = generateStatement(path, 'SELECT', 'get', [ + field('owner', 'input_required'), + field('page', 'input_required', 'integer'), + field('id', 'output'), + ]); + expect(sql).toContain("WHERE owner = ''\n AND page = ;"); + }); + + it('counts a field the engine calls a response as an output', () => { + const sql = generateStatement(path, 'SELECT', 'get', [field('vpc_id', 'response')]); + expect(sql).toContain('SELECT\n vpc_id\nFROM'); + expect(sql).not.toContain('WHERE'); + }); + + it('selects everything when the outputs are not known', () => { + expect(generateStatement(path, 'SELECT', 'get', [field('org', 'input_required')])).toContain( + 'SELECT\n *\nFROM github.repos.repos\nWHERE', + ); + }); + + it('builds INSERT from the required inputs', () => { + const sql = generateStatement(path, 'INSERT', 'create_in_org', [ + field('org', 'input_required'), + field('name', 'input_required'), + field('private', 'input_optional', 'boolean'), + field('id', 'output'), + ]); + expect(sql).toContain( + "INSERT INTO github.repos.repos (\n org,\n name\n)\nSELECT\n '',\n '';", + ); + expect(sql).not.toContain('private'); + }); + + it('puts optional inputs in SET and required ones in WHERE for UPDATE and REPLACE', () => { + const inputs = [ + field('owner', 'input_required'), + field('repo', 'input_required'), + field('description', 'input_optional'), + ]; + const update = generateStatement(path, 'UPDATE', 'update', inputs); + expect(update).toContain( + "UPDATE github.repos.repos\nSET\n description = ''\nWHERE owner = ''\n AND repo = '';", + ); + expect(generateStatement(path, 'replace', 'replace', inputs)).toContain( + 'REPLACE github.repos.repos\nSET', + ); + }); + + it('builds DELETE and EXEC from the required inputs', () => { + const inputs = [field('owner', 'input_required'), field('repo', 'input_required')]; + expect(generateStatement(path, 'DELETE', 'delete', inputs)).toContain( + "DELETE FROM github.repos.repos\nWHERE owner = ''\n AND repo = '';", + ); + expect(generateStatement(path, 'EXEC', 'list_languages', inputs)).toContain( + "EXEC github.repos.repos.list_languages\n @owner = '',\n @repo = '';", + ); + }); + + it('still gives a usable shape when a method takes nothing', () => { + expect(generateStatement(path, 'DELETE', 'purge', [])).toContain( + 'DELETE FROM github.repos.repos;', + ); + expect(generateStatement(path, 'EXEC', 'sync', [])).toContain('EXEC github.repos.repos.sync;'); + expect(generateStatement(path, 'INSERT', 'create', [])).toContain(''); + expect(generateStatement(path, 'UPDATE', 'touch', [])).toContain(" = ''"); + }); + + it('puts a note under the first line', () => { + const sql = generateStatement(path, 'SELECT', 'list_public', [], '-- A note.'); + expect(sql.split('\n').slice(0, 3)).toEqual([ + '-- github.repos.repos, method list_public (SELECT).', + '-- A note.', + 'SELECT', + ]); + }); + + it('asks for placeholders to be filled in only when there are some', () => { + const none = generateStatement(path, 'SELECT', 'list_public', [field('name', 'output')]); + expect(none).not.toContain('placeholder'); + expect(none).toContain('SELECT\n name\nFROM github.repos.repos;'); + expect( + generateStatement(path, 'DELETE', 'delete', [field('repo', 'input_required')]), + ).toContain('Fill in each before running.'); + }); + + it('says so when it has no template for a verb', () => { + expect(generateStatement(path, 'MERGE', 'merge', [])).toContain( + 'no template for the verb MERGE', + ); + }); + + it('quotes names that are not plain identifiers', () => { + const sql = generateStatement( + { provider: 'aws', service: 'ec2', resource: 'my-res' }, + 'SELECT', + 'get', + [field('odd-param', 'input_required'), field('some col', 'output')], + ); + expect(sql).toContain('FROM aws.ec2."my-res"'); + expect(sql).toContain('"some col"'); + expect(sql).toContain('WHERE "odd-param" = \'\''); + }); +}); diff --git a/src/lib/generateSql.ts b/src/lib/generateSql.ts new file mode 100644 index 0000000..167b1fb --- /dev/null +++ b/src/lib/generateSql.ts @@ -0,0 +1,136 @@ +// Statement templates for a resource or a method, built from what the +// engine says about the method's inputs and outputs. They are opened in +// the editor for the operator to fill in. Nothing here runs anything, and +// nothing here decides what a statement does. +// +// The shapes follow the engine's own guidance on its dialect. + +import type { Method, MethodField } from '../host/types'; +import type { NodePath } from './explorerTree'; + +const PLAIN = /^[A-Za-z_][A-Za-z0-9_]*$/; + +/** A name as it is written in a statement: bare when plain, quoted when not. */ +export function ident(name: string): string { + return PLAIN.test(name) ? name : `"${name.replace(/"/g, '""')}"`; +} + +/** `provider.service.resource`, each part written as an identifier. */ +export function tableName(path: NodePath): string { + return [path.provider, path.service, path.resource] + .filter((part): part is string => part !== undefined) + .map(ident) + .join('.'); +} + +const isInput = (field: MethodField) => field.paramType.startsWith('input'); +const isRequired = (field: MethodField) => field.paramType === 'input_required'; +const UNQUOTED = new Set(['integer', 'number', 'boolean', 'int', 'bigint', 'float', 'double']); + +/** What stands in for a value the operator has to supply. */ +function placeholder(field: MethodField): string { + const mark = `<${field.name}>`; + return UNQUOTED.has(field.type.toLowerCase()) ? mark : `'${mark}'`; +} + +function whereClause(fields: MethodField[]): string { + return fields + .map( + (field, index) => + `${index === 0 ? 'WHERE' : ' AND'} ${ident(field.name)} = ${placeholder(field)}`, + ) + .join('\n'); +} + +/** + * The SELECT method a statement on the resource is most likely to route + * to: the one that needs the fewest parameters. Null when there is none. + */ +export function pickSelectMethod(methods: Method[]): Method | null { + const selects = methods.filter((method) => method.sqlVerb.toUpperCase() === 'SELECT'); + selects.sort( + (a, b) => a.requiredParams.length - b.requiredParams.length || a.name.localeCompare(b.name), + ); + return selects[0] ?? null; +} + +/** + * A comment naming the SELECT methods that were not picked, with what each + * needs, so the operator can see the other ways to read the resource. + * Empty when there is no other. + */ +export function otherSelectMethods(methods: Method[], picked: Method): string { + const others = methods + .filter((method) => method.sqlVerb.toUpperCase() === 'SELECT' && method.name !== picked.name) + .map((method) => + method.requiredParams.length > 0 + ? `${method.name} (${method.requiredParams.join(', ')})` + : method.name, + ); + return others.length > 0 + ? `-- Other SELECT methods, with what each requires: ${others.join('; ')}.` + : ''; +} + +/** + * A statement template for one method. `verb` is the SQL verb the engine + * reports for it. Values to fill in are written as ``. `note` is a + * comment line to put under the first one. + */ +export function generateStatement( + path: NodePath, + verb: string, + method: string, + fields: MethodField[], + note = '', +): string { + const table = tableName(path); + const inputs = fields.filter(isInput); + const required = inputs.filter(isRequired); + const optional = inputs.filter((field) => !isRequired(field)); + const outputs = fields.filter((field) => !isInput(field)); + const upper = verb.toUpperCase(); + const lines = (items: string[]) => items.map((item) => ` ${item}`).join(',\n'); + const where = required.length > 0 ? `\n${whereClause(required)}` : ''; + + const body = (): string => { + switch (upper) { + case 'SELECT': { + const columns = outputs.length > 0 ? lines(outputs.map((f) => ident(f.name))) : ' *'; + return `SELECT\n${columns}\nFROM ${table}${where};`; + } + case 'INSERT': { + // With nothing required, list what can be set and let the operator trim. + const set = required.length > 0 ? required : inputs; + if (set.length === 0) { + return `INSERT INTO ${table} (\n \n)\nSELECT\n '';`; + } + return `INSERT INTO ${table} (\n${lines(set.map((f) => ident(f.name)))}\n)\nSELECT\n${lines(set.map(placeholder))};`; + } + case 'UPDATE': + case 'REPLACE': { + const set = + optional.length > 0 + ? lines(optional.map((f) => `${ident(f.name)} = ${placeholder(f)}`)) + : " = ''"; + return `-- Keep only the fields to change in SET.\n${upper} ${table}\nSET\n${set}${where};`; + } + case 'DELETE': + return `DELETE FROM ${table}${where};`; + case 'EXEC': { + const args = + required.length > 0 + ? `\n${lines(required.map((f) => `@${ident(f.name)} = ${placeholder(f)}`))}` + : ''; + return `EXEC ${table}.${ident(method)}${args};`; + } + default: + return `-- There is no template for the verb ${upper}.`; + } + }; + + const statement = body(); + const fill = /<[^>\s]+>/.test(statement) ? ' Fill in each before running.' : ''; + const first = `-- ${table}, method ${method} (${upper}).${fill}`; + return `${note === '' ? first : `${first}\n${note}`}\n${statement}\n`; +} diff --git a/src/lib/history.test.ts b/src/lib/history.test.ts new file mode 100644 index 0000000..d90dfc8 --- /dev/null +++ b/src/lib/history.test.ts @@ -0,0 +1,68 @@ +import { describe, expect, it } from 'vitest'; +import type { HistoryEntry } from '../host/types'; +import { oneLine, recentStatements, timeAgo } from './history'; + +const entry = (sql: string, timestampMs: number, outcome = 'ok'): HistoryEntry => ({ + timestampMs, + sql, + outcome, + rows: null, + elapsedMs: 1, + error: null, +}); + +describe('recentStatements', () => { + it('lists the most recently run first', () => { + const items = recentStatements([ + entry('SHOW PROVIDERS', 100), + entry('REGISTRY LIST', 300), + entry('SHOW VERSION', 200), + ]); + expect(items.map((item) => item.sql)).toEqual([ + 'REGISTRY LIST', + 'SHOW VERSION', + 'SHOW PROVIDERS', + ]); + }); + + it('lists a statement once, with its last run and a count', () => { + const items = recentStatements([ + entry('SHOW PROVIDERS', 100), + entry('SHOW VERSION', 150), + entry(' SHOW PROVIDERS\n', 300, 'error'), + ]); + expect(items).toEqual([ + { sql: 'SHOW PROVIDERS', timestampMs: 300, outcome: 'error', runs: 2 }, + { sql: 'SHOW VERSION', timestampMs: 150, outcome: 'ok', runs: 1 }, + ]); + }); + + it('keeps what holds the search text, whatever its case', () => { + const items = recentStatements( + [entry('SELECT login FROM github.orgs.orgs', 1), entry('SHOW PROVIDERS', 2)], + ' GITHUB ', + ); + expect(items.map((item) => item.sql)).toEqual(['SELECT login FROM github.orgs.orgs']); + }); + + it('leaves out an empty statement', () => { + expect(recentStatements([entry(' ', 1)])).toEqual([]); + }); +}); + +describe('oneLine', () => { + it('folds line breaks and runs of spaces', () => { + expect(oneLine('SELECT a,\n b\nFROM t ')).toBe('SELECT a, b FROM t'); + }); +}); + +describe('timeAgo', () => { + it('gives a short phrase', () => { + const now = 10_000_000_000; + expect(timeAgo(now - 20_000, now)).toBe('just now'); + expect(timeAgo(now - 5 * 60_000, now)).toBe('5 min ago'); + expect(timeAgo(now - 3 * 3_600_000, now)).toBe('3 h ago'); + expect(timeAgo(now - 2 * 86_400_000, now)).toBe('2 d ago'); + expect(timeAgo(now + 5_000, now)).toBe('just now'); + }); +}); diff --git a/src/lib/history.ts b/src/lib/history.ts new file mode 100644 index 0000000..da9e99f --- /dev/null +++ b/src/lib/history.ts @@ -0,0 +1,66 @@ +// The editor's statement history: what the operator ran, most recent +// first, each statement listed once. Statements only, never results. + +import type { HistoryEntry } from '../host/types'; + +export interface HistoryItem { + sql: string; + /** When it was last run. Milliseconds since the Unix epoch. */ + timestampMs: number; + /** How the last run ended: ok, error or abandoned. */ + outcome: string; + /** How many times it was run. */ + runs: number; +} + +/** + * The statements in `entries`, most recently run first. Runs of the same + * statement are folded into one item. `search` keeps the items that hold + * the text, whatever its case. + */ +export function recentStatements(entries: HistoryEntry[], search = ''): HistoryItem[] { + const items = new Map(); + for (const entry of entries) { + const sql = entry.sql.trim(); + if (sql === '') { + continue; + } + const known = items.get(sql); + if (!known) { + items.set(sql, { sql, timestampMs: entry.timestampMs, outcome: entry.outcome, runs: 1 }); + } else { + known.runs += 1; + if (entry.timestampMs >= known.timestampMs) { + known.timestampMs = entry.timestampMs; + known.outcome = entry.outcome; + } + } + } + const text = search.trim().toLowerCase(); + return [...items.values()] + .filter((item) => text === '' || item.sql.toLowerCase().includes(text)) + .sort((a, b) => b.timestampMs - a.timestampMs); +} + +/** A statement on one line, for a list. */ +export function oneLine(sql: string): string { + return sql.replace(/\s+/g, ' ').trim(); +} + +/** How long ago something happened, in words short enough for a list. */ +export function timeAgo(timestampMs: number, nowMs: number): string { + const seconds = Math.max(0, Math.round((nowMs - timestampMs) / 1000)); + if (seconds < 60) { + return 'just now'; + } + const minutes = Math.round(seconds / 60); + if (minutes < 60) { + return `${minutes} min ago`; + } + const hours = Math.round(minutes / 60); + if (hours < 24) { + return `${hours} h ago`; + } + const days = Math.round(hours / 24); + return `${days} d ago`; +} diff --git a/src/lib/library.test.ts b/src/lib/library.test.ts new file mode 100644 index 0000000..25a369f --- /dev/null +++ b/src/lib/library.test.ts @@ -0,0 +1,216 @@ +import { describe, expect, it } from 'vitest'; +import type { LibraryEntry } from '../host/types'; +import { + FALLBACK_SUGGESTIONS, + METADATA_SUGGESTION, + chatSuggestions, + editorText, + filterEntries, + groupEntries, + librarySuggestions, + missingProviders, + placeholders, + usable, + entryUseCase, +} from './library'; + +const entry = (id: string, over: Partial = {}): LibraryEntry => ({ + id, + title: id, + description: '', + providers: [id.split('/')[0] ?? ''], + services: [], + tags: [], + keywords: [], + intentKeywords: [], + mutation: false, + verb: 'select', + status: 'stable', + requiredParams: [], + ...over, +}); + +const repos = entry('github/repos/org-repos-list', { + title: 'GitHub repositories in an organization', + description: 'Lists all repositories in a GitHub organization.', + tags: ['github', 'repos', 'inventory'], + keywords: ['repo list', 'stale repos'], + intentKeywords: ['list repos in my github org'], + requiredParams: ['org'], +}); +const buckets = entry('aws/s3/buckets-list', { + title: 'S3 buckets', + tags: ['aws', 's3', 'storage', 'inventory'], + intentKeywords: ['list my s3 buckets'], +}); +const mfa = entry('aws/iam/users-console-no-mfa', { + title: 'Console users without MFA', + tags: ['aws', 'iam', 'security', 'cspm', 'mfa'], + intentKeywords: ['which iam users have no mfa'], +}); +const create = entry('aws/ec2/instance-create', { + title: 'Create an instance', + providers: ['awscc'], + tags: ['aws', 'ec2', 'compute', 'provisioning', 'mutation'], + mutation: true, + verb: 'mutation', + status: 'draft', + intentKeywords: ['launch an ec2 instance'], +}); +const trend = entry('github/repos/commit-activity-trend', { + title: 'Commit activity', + tags: ['github', 'repos', 'analytics', 'activity'], + intentKeywords: ['how active is this repository'], + requiredParams: ['owner', 'repo'], +}); +const stars = entry('github/activity/repo-stargazers', { + title: 'Stargazers', + tags: ['github', 'activity', 'community', 'stars'], +}); +const all = [repos, buckets, mfa, create, trend, stars]; + +describe('entryUseCase', () => { + it('takes the first tag that names a use case', () => { + expect(entryUseCase(repos).key).toBe('inventory'); + expect(entryUseCase(mfa).key).toBe('security'); + expect(entryUseCase(trend).key).toBe('analytics'); + expect(entryUseCase(create)).toEqual({ key: 'lifecycle', label: 'Lifecycle and operations' }); + }); + + it('files an entry with no such tag under Other', () => { + expect(entryUseCase(stars)).toEqual({ key: 'other', label: 'Other' }); + }); +}); + +describe('usable', () => { + it('needs every provider an entry names', () => { + expect(usable(repos, new Set(['github']))).toBe(true); + expect(usable(repos, new Set(['aws']))).toBe(false); + expect(usable(entry('x/y/z', { providers: ['aws', 'github'] }), new Set(['aws']))).toBe(false); + expect(usable(entry('x/y/z', { providers: [] }), new Set(['aws']))).toBe(false); + expect(missingProviders(create, new Set(['aws']))).toEqual(['awscc']); + }); +}); + +describe('filterEntries', () => { + const installed = new Set(['github']); + + it('keeps the entries for installed providers by default', () => { + const shown = filterEntries(all, { search: '', installed, installedOnly: true }); + expect(shown.map((item) => item.id)).toEqual([ + 'github/repos/org-repos-list', + 'github/repos/commit-activity-trend', + 'github/activity/repo-stargazers', + ]); + }); + + it('shows everything when asked', () => { + expect(filterEntries(all, { search: '', installed, installedOnly: false })).toHaveLength(6); + }); + + it('finds an entry by any of its words, whatever their case', () => { + const find = (search: string) => + filterEntries(all, { search, installed, installedOnly: false }).map((item) => item.id); + expect(find('STALE')).toEqual(['github/repos/org-repos-list']); + expect(find('mfa')).toEqual(['aws/iam/users-console-no-mfa']); + expect(find('aws inventory')).toEqual(['aws/s3/buckets-list']); + expect(find('list repos in my github org')).toEqual(['github/repos/org-repos-list']); + expect(find('nothing-like-this')).toEqual([]); + }); +}); + +describe('groupEntries', () => { + it('lists the use cases in a fixed order, and each group by provider then title', () => { + const groups = groupEntries(all); + expect(groups.map((group) => group.useCase.label)).toEqual([ + 'Security', + 'Analytics', + 'Inventory', + 'Lifecycle and operations', + 'Other', + ]); + const inventory = groups.find((group) => group.useCase.key === 'inventory'); + expect(inventory?.entries.map((item) => item.id)).toEqual([ + 'aws/s3/buckets-list', + 'github/repos/org-repos-list', + ]); + }); + + it('has no group for a use case with no entries', () => { + expect(groupEntries([])).toEqual([]); + expect(groupEntries([stars]).map((group) => group.useCase.key)).toEqual(['other']); + }); +}); + +describe('placeholders', () => { + it('lists each name once, in order', () => { + expect( + placeholders( + "SELECT name FROM github.repos.repos WHERE org = '{{org}}' AND type = '{{ repo_type }}' AND x = '{{org}}'", + ), + ).toEqual(['org', 'repo_type']); + expect(placeholders('SELECT 1')).toEqual([]); + }); +}); + +describe('editorText', () => { + it('says where the statement came from and what to fill in', () => { + expect( + editorText(repos, "SELECT name\nFROM github.repos.repos\nWHERE org = '{{org}}';\n"), + ).toBe( + [ + '-- GitHub repositories in an organization (query library: github/repos/org-repos-list)', + '-- Replace each {{name}} before running: org.', + 'SELECT name', + 'FROM github.repos.repos', + "WHERE org = '{{org}}';", + '', + ].join('\n'), + ); + }); + + it('leaves the second line out when nothing needs filling in', () => { + expect(editorText(buckets, 'SELECT name FROM aws.s3.buckets;').split('\n')).toEqual([ + '-- S3 buckets (query library: aws/s3/buckets-list)', + 'SELECT name FROM aws.s3.buckets;', + '', + ]); + }); +}); + +describe('librarySuggestions', () => { + it('offers stable, read-only entries for installed providers', () => { + expect(librarySuggestions(all, new Set(['github']), 2)).toEqual([ + 'List repos in my github org', + 'How active is this repository', + ]); + }); + + it('puts entries that need nothing filled in first, and varies the provider', () => { + expect(librarySuggestions(all, new Set(['github', 'aws', 'awscc']), 2)).toEqual([ + 'List my s3 buckets', + 'List repos in my github org', + ]); + }); + + it('never offers a draft, a mutation or an entry with nothing to ask', () => { + const offered = librarySuggestions(all, new Set(['github', 'aws', 'awscc']), 10); + expect(offered).not.toContain('Launch an ec2 instance'); + expect(offered).toHaveLength(4); + }); +}); + +describe('chatSuggestions', () => { + it('keeps one question about metadata and takes the rest from the library', () => { + expect(chatSuggestions(all, new Set(['github']))).toEqual([ + METADATA_SUGGESTION, + 'List repos in my github org', + 'How active is this repository', + ]); + }); + + it('falls back when the library has nothing for what is installed', () => { + expect(chatSuggestions(all, new Set(['homebrew']))).toEqual(FALLBACK_SUGGESTIONS); + expect(chatSuggestions([], new Set(['github']))).toEqual(FALLBACK_SUGGESTIONS); + }); +}); diff --git a/src/lib/library.ts b/src/lib/library.ts new file mode 100644 index 0000000..c391f79 --- /dev/null +++ b/src/lib/library.ts @@ -0,0 +1,201 @@ +// The query library as the operator sees it: entries grouped by use case, +// narrowed to the providers that are installed, and searched. The entries +// and everything said about them come from the library's own index. + +import type { LibraryEntry } from '../host/types'; + +export interface UseCase { + key: string; + label: string; +} + +/** + * The use cases entries are listed under, in the order they are shown, with + * the library tags that name each. + */ +const USE_CASES: (UseCase & { tags: string[] })[] = [ + { key: 'security', label: 'Security', tags: ['security', 'cspm', 'compliance'] }, + { key: 'analytics', label: 'Analytics', tags: ['analytics'] }, + { key: 'inventory', label: 'Inventory', tags: ['inventory'] }, + { + key: 'lifecycle', + label: 'Lifecycle and operations', + tags: ['lifecycle', 'provisioning', 'operations', 'mutation', 'bootstrap'], + }, + { key: 'reference', label: 'Reference', tags: ['reference'] }, +]; +const OTHER: UseCase = { key: 'other', label: 'Other' }; + +/** The use case an entry is listed under: the first of its tags that names one. */ +export function entryUseCase(entry: LibraryEntry): UseCase { + for (const tag of entry.tags) { + const found = USE_CASES.find((useCase) => useCase.tags.includes(tag)); + if (found) { + return { key: found.key, label: found.label }; + } + } + return OTHER; +} + +/** Whether every provider an entry names is installed. */ +export function usable(entry: LibraryEntry, installed: ReadonlySet): boolean { + return entry.providers.length > 0 && entry.providers.every((name) => installed.has(name)); +} + +/** The providers an entry names that are not installed. */ +export function missingProviders(entry: LibraryEntry, installed: ReadonlySet): string[] { + return entry.providers.filter((name) => !installed.has(name)); +} + +export interface LibraryFilter { + /** Words that must all appear in an entry. */ + search: string; + installed: ReadonlySet; + /** Leave out entries for providers that are not installed. */ + installedOnly: boolean; +} + +function haystack(entry: LibraryEntry): string { + return [ + entry.id, + entry.title, + entry.description, + ...entry.providers, + ...entry.services, + ...entry.tags, + ...entry.keywords, + ...entry.intentKeywords, + ] + .join('\n') + .toLowerCase(); +} + +export function filterEntries(entries: LibraryEntry[], filter: LibraryFilter): LibraryEntry[] { + const words = filter.search.toLowerCase().split(/\s+/).filter(Boolean); + return entries.filter((entry) => { + if (filter.installedOnly && !usable(entry, filter.installed)) { + return false; + } + if (words.length === 0) { + return true; + } + const text = haystack(entry); + return words.every((word) => text.includes(word)); + }); +} + +export interface LibraryGroup { + useCase: UseCase; + entries: LibraryEntry[]; +} + +/** Entries under their use case, each group by provider and then title. */ +export function groupEntries(entries: LibraryEntry[]): LibraryGroup[] { + const groups = new Map(); + for (const entry of entries) { + const useCase = entryUseCase(entry); + const group = groups.get(useCase.key) ?? { useCase, entries: [] }; + group.entries.push(entry); + groups.set(useCase.key, group); + } + const order = [...USE_CASES.map((useCase) => useCase.key), OTHER.key]; + return order.flatMap((key) => { + const group = groups.get(key); + if (!group) { + return []; + } + group.entries.sort( + (a, b) => + (a.providers[0] ?? '').localeCompare(b.providers[0] ?? '') || + a.title.localeCompare(b.title), + ); + return [group]; + }); +} + +/** The names a template asks for, written `{{name}}`, each once and in order. */ +export function placeholders(statement: string): string[] { + const names: string[] = []; + for (const match of statement.matchAll(/\{\{\s*([A-Za-z_][\w-]*)\s*\}\}/g)) { + const name = match[1]; + if (name !== undefined && !names.includes(name)) { + names.push(name); + } + } + return names; +} + +/** + * What goes in the editor for an entry's statement: where it came from, + * what has to be filled in, and the statement as the library has it. + */ +export function editorText(entry: Pick, statement: string): string { + const names = placeholders(statement); + return [ + `-- ${entry.title} (query library: ${entry.id})`, + ...(names.length > 0 ? [`-- Replace each {{name}} before running: ${names.join(', ')}.`] : []), + statement.trim(), + '', + ].join('\n'); +} + +const sentence = (text: string) => text.charAt(0).toUpperCase() + text.slice(1); + +/** + * Things to ask, taken from library entries that can run here: stable, + * read-only, and for installed providers. Entries that need nothing filled + * in come first, and each provider is used once before any is used twice. + */ +export function librarySuggestions( + entries: LibraryEntry[], + installed: ReadonlySet, + limit: number, +): string[] { + const candidates = entries + .filter( + (entry) => + usable(entry, installed) && + entry.status === 'stable' && + !entry.mutation && + (entry.intentKeywords[0] ?? '') !== '', + ) + .map((entry, position) => ({ entry, position })) + .sort( + (a, b) => + a.entry.requiredParams.length - b.entry.requiredParams.length || a.position - b.position, + ) + .map(({ entry }) => entry); + + const picked: LibraryEntry[] = []; + const used = new Set(); + for (const pass of [true, false]) { + for (const entry of candidates) { + if (picked.length >= limit) { + break; + } + const provider = entry.providers[0] ?? ''; + if (picked.includes(entry) || (pass && used.has(provider))) { + continue; + } + picked.push(entry); + used.add(provider); + } + } + return picked.map((entry) => sentence(entry.intentKeywords[0] ?? '')); +} + +/** A question about what is installed. It needs no credentials and no library. */ +export const METADATA_SUGGESTION = 'Which providers are installed?'; + +/** What is offered when the library has nothing for the installed providers. */ +export const FALLBACK_SUGGESTIONS = [ + METADATA_SUGGESTION, + 'What providers can I install from the registry?', + 'What can I query in the github provider?', +]; + +/** The chips under an empty chat: one about metadata, the rest from the library. */ +export function chatSuggestions(entries: LibraryEntry[], installed: ReadonlySet): string[] { + const fromLibrary = librarySuggestions(entries, installed, 2); + return fromLibrary.length > 0 ? [METADATA_SUGGESTION, ...fromLibrary] : FALLBACK_SUGGESTIONS; +} diff --git a/src/lib/markdown.test.ts b/src/lib/markdown.test.ts new file mode 100644 index 0000000..899aba8 --- /dev/null +++ b/src/lib/markdown.test.ts @@ -0,0 +1,162 @@ +import { describe, expect, it } from 'vitest'; +import { parseBlocks, parseInline, type Inline } from './markdown'; + +/** A compact rendering of inline nodes, to keep the expectations readable. */ +function show(nodes: Inline[]): string { + return nodes + .map((node) => { + switch (node.kind) { + case 'text': + return node.text; + case 'strong': + return `${show(node.children)}`; + case 'em': + return `${show(node.children)}`; + case 'code': + return `${node.text}`; + case 'link': + return `${show(node.children)}`; + } + }) + .join(''); +} + +const inline = (text: string) => show(parseInline(text)); + +describe('parseInline', () => { + it('reads bold, italic and code', () => { + expect(inline('Only **stackql_preview** is installed.')).toBe( + 'Only stackql_preview is installed.', + ); + expect(inline('an *important* point and _another_')).toBe( + 'an important point and another', + ); + expect(inline('run `SHOW PROVIDERS` first')).toBe('run SHOW PROVIDERS first'); + expect(inline('**bold with `code` inside**')).toBe('bold with code inside'); + }); + + it('leaves names with underscores alone', () => { + expect(inline('the run_select_query tool and stackql_preview')).toBe( + 'the run_select_query tool and stackql_preview', + ); + expect(inline('aws.ec2.instances has instance_id and instance_type')).toBe( + 'aws.ec2.instances has instance_id and instance_type', + ); + }); + + it('leaves SQL stars alone', () => { + expect(inline('SELECT * FROM a WHERE b * c > 1')).toBe('SELECT * FROM a WHERE b * c > 1'); + expect(inline('SELECT COUNT(*) FROM a and COUNT(*) FROM b')).toBe( + 'SELECT COUNT(*) FROM a and COUNT(*) FROM b', + ); + expect(inline('2 * 3 * 4')).toBe('2 * 3 * 4'); + }); + + it('leaves markers that never close as text', () => { + expect(inline('a **bold that is still being typed')).toBe('a **bold that is still being typed'); + expect(inline('a `code that never ends')).toBe('a `code that never ends'); + expect(inline('one *star')).toBe('one *star'); + }); + + it('reads links and keeps their address', () => { + expect(inline('see [the docs](https://stackql.io/docs) for more')).toBe( + 'see the docs for more', + ); + expect(inline('an [array] index and (parens)')).toBe('an [array] index and (parens)'); + }); + + it('does not treat code as markup', () => { + expect(inline('`**not bold**` and `a_b_c`')).toBe( + '**not bold** and a_b_c', + ); + }); +}); + +describe('parseBlocks', () => { + it('splits paragraphs on blank lines and keeps line breaks inside one', () => { + const blocks = parseBlocks('First line\nsecond line\n\nNext paragraph'); + expect(blocks).toHaveLength(2); + expect(blocks[0]).toMatchObject({ kind: 'paragraph' }); + expect(blocks[0]?.kind === 'paragraph' && blocks[0].lines.map(show)).toEqual([ + 'First line', + 'second line', + ]); + }); + + it('reads headings and caps their level', () => { + const blocks = parseBlocks('# Title\n## Section\n##### Deep'); + expect(blocks.map((b) => (b.kind === 'heading' ? [b.level, show(b.content)] : null))).toEqual([ + [1, 'Title'], + [2, 'Section'], + [3, 'Deep'], + ]); + }); + + it('does not read a hash without a space as a heading', () => { + expect(parseBlocks('#hashtag')[0]?.kind).toBe('paragraph'); + }); + + it('reads a bullet list with nesting and continuation lines', () => { + const [list] = parseBlocks('- one\n- two\n carries on\n - nested **bold**\n- three'); + expect(list).toMatchObject({ kind: 'list', ordered: false }); + expect(list?.kind === 'list' && list.items.map((i) => [i.depth, show(i.content)])).toEqual([ + [0, 'one'], + [0, 'two carries on'], + [1, 'nested bold'], + [0, 'three'], + ]); + }); + + it('reads a numbered list and where it starts', () => { + const [list] = parseBlocks('3. third\n4. fourth'); + expect(list).toMatchObject({ kind: 'list', ordered: true, start: 3 }); + expect(list?.kind === 'list' && list.items).toHaveLength(2); + }); + + it('reads a table', () => { + const [table] = parseBlocks( + '| Bucket | Region |\n|---|---|\n| alpine-analytics-lake | us-east-1 |\n| `a|b` | us-west-2 |', + ); + expect(table?.kind).toBe('table'); + if (table?.kind !== 'table') { + return; + } + expect(table.header.map(show)).toEqual(['Bucket', 'Region']); + expect(table.rows.map((row) => row.map(show))).toEqual([ + ['alpine-analytics-lake', 'us-east-1'], + ['a|b', 'us-west-2'], + ]); + }); + + it('keeps a table square when rows are short or long', () => { + const [table] = parseBlocks('a | b\n--|--\n| 1 |\n1 | 2 | 3'); + expect(table?.kind === 'table' && table.rows.map((row) => row.map(show))).toEqual([ + ['1', ''], + ['1', '2'], + ]); + }); + + it('does not read a line with a pipe as a table without the dashes', () => { + expect(parseBlocks('a | b\nc | d')[0]?.kind).toBe('paragraph'); + }); + + it('reads a rule and carries on', () => { + expect(parseBlocks('above\n\n---\n\nbelow').map((b) => b.kind)).toEqual([ + 'paragraph', + 'rule', + 'paragraph', + ]); + }); + + it('reads a reply with several kinds of block', () => { + const blocks = parseBlocks( + 'Found **65 S3 buckets** across 6 regions.\n\n| Bucket | Region |\n|---|---|\n| a | us-east-1 |\n\nNext steps:\n1. Pick a region\n2. Run the query', + ); + expect(blocks.map((b) => b.kind)).toEqual(['paragraph', 'table', 'paragraph', 'list']); + }); + + it('has nothing for empty text', () => { + expect(parseBlocks('')).toEqual([]); + expect(parseBlocks(' \n\n ')).toEqual([]); + }); +}); diff --git a/src/lib/markdown.ts b/src/lib/markdown.ts new file mode 100644 index 0000000..a5a2243 --- /dev/null +++ b/src/lib/markdown.ts @@ -0,0 +1,266 @@ +// A small reader for the markdown models write in replies: headings, lists, +// tables, emphasis, inline code and links. Fenced code is split out before +// this runs. See `splitFences`. +// +// It produces a tree and never HTML, so nothing a model writes can become +// markup. Text it does not recognise stays as it was typed. + +export type Inline = + | { kind: 'text'; text: string } + | { kind: 'strong'; children: Inline[] } + | { kind: 'em'; children: Inline[] } + | { kind: 'code'; text: string } + | { kind: 'link'; children: Inline[]; url: string }; + +export interface ListItem { + /** How far the item is indented, from 0. */ + depth: number; + content: Inline[]; +} + +export type Block = + | { kind: 'paragraph'; lines: Inline[][] } + | { kind: 'heading'; level: 1 | 2 | 3; content: Inline[] } + | { kind: 'list'; ordered: boolean; start: number; items: ListItem[] } + | { kind: 'table'; header: Inline[][]; rows: Inline[][][] } + | { kind: 'rule' }; + +const WORD = /[\p{L}\p{N}_]/u; +const isWord = (char: string | undefined) => char !== undefined && WORD.test(char); +const isSpace = (char: string | undefined) => char === undefined || /\s/.test(char); + +/** + * Finds the end of an emphasis run that opens at `from` with `marker`. + * The closing marker must follow something that is not a space. + */ +function closing(text: string, marker: string, from: number): number { + let at = text.indexOf(marker, from); + while (at !== -1) { + if (at > from && !isSpace(text[at - 1])) { + return at; + } + at = text.indexOf(marker, at + 1); + } + return -1; +} + +/** Reads emphasis, inline code and links out of one run of text. */ +export function parseInline(text: string): Inline[] { + const out: Inline[] = []; + let plain = ''; + const flush = () => { + if (plain !== '') { + out.push({ kind: 'text', text: plain }); + plain = ''; + } + }; + + let i = 0; + while (i < text.length) { + const char = text.charAt(i); + const before = text[i - 1]; + + if (char === '`') { + const end = text.indexOf('`', i + 1); + if (end > i + 1) { + flush(); + out.push({ kind: 'code', text: text.slice(i + 1, end) }); + i = end + 1; + continue; + } + } else if (char === '*' && text[i + 1] === '*') { + const end = closing(text, '**', i + 2); + if (end !== -1 && !isSpace(text[i + 2])) { + flush(); + out.push({ kind: 'strong', children: parseInline(text.slice(i + 2, end)) }); + i = end + 2; + continue; + } + } else if (char === '*' || char === '_') { + // A single marker opens emphasis only at the start of a word. That + // keeps snake_case names, SELECT * and COUNT(*) as they were typed. + const opens = !isWord(before) && before !== '(' && before !== char && isWord(text[i + 1]); + if (opens) { + let end = closing(text, char, i + 1); + // The closing marker must end a word, not sit inside one. + while (end !== -1 && (isWord(text[end + 1]) || text[end + 1] === char)) { + end = closing(text, char, end + 1); + } + if (end !== -1) { + flush(); + out.push({ kind: 'em', children: parseInline(text.slice(i + 1, end)) }); + i = end + 1; + continue; + } + } + } else if (char === '[') { + const label = text.indexOf('](', i + 1); + const end = label === -1 ? -1 : text.indexOf(')', label + 2); + if (label > i + 1 && end !== -1 && !text.slice(i + 1, label).includes('\n')) { + const url = text.slice(label + 2, end).trim(); + if (url !== '' && !/\s/.test(url)) { + flush(); + out.push({ kind: 'link', children: parseInline(text.slice(i + 1, label)), url }); + i = end + 1; + continue; + } + } + } + plain += char; + i += 1; + } + flush(); + return out; +} + +const HEADING = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/; +const RULE = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/; +const BULLET = /^(\s*)[-*+]\s+(.*)$/; +const NUMBERED = /^(\s*)(\d{1,9})[.)]\s+(.*)$/; +const TABLE_RULE = /^\s*\|?\s*:?-{1,}:?\s*(?:\|\s*:?-{1,}:?\s*)*\|?\s*$/; + +/** The cells of one table row. A pipe inside inline code is not a divider. */ +function cells(line: string): string[] { + const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, ''); + const out: string[] = []; + let cell = ''; + let inCode = false; + for (let i = 0; i < trimmed.length; i += 1) { + const char = trimmed.charAt(i); + if (char === '`') { + inCode = !inCode; + } + if (char === '\\' && trimmed[i + 1] === '|') { + cell += '|'; + i += 1; + } else if (char === '|' && !inCode) { + out.push(cell.trim()); + cell = ''; + } else { + cell += char; + } + } + out.push(cell.trim()); + return out; +} + +function listMatch( + line: string, +): { ordered: boolean; start: number; indent: number; text: string } | null { + const bullet = BULLET.exec(line); + if (bullet) { + return { ordered: false, start: 1, indent: (bullet[1] ?? '').length, text: bullet[2] ?? '' }; + } + const numbered = NUMBERED.exec(line); + if (numbered) { + return { + ordered: true, + start: Number(numbered[2]), + indent: (numbered[1] ?? '').length, + text: numbered[3] ?? '', + }; + } + return null; +} + +/** Reads text into blocks. */ +export function parseBlocks(text: string): Block[] { + const lines = text.replace(/\r\n?/g, '\n').split('\n'); + const blocks: Block[] = []; + let paragraph: string[] = []; + const endParagraph = () => { + if (paragraph.length > 0) { + blocks.push({ kind: 'paragraph', lines: paragraph.map(parseInline) }); + paragraph = []; + } + }; + + let i = 0; + while (i < lines.length) { + const line = lines[i] ?? ''; + + if (line.trim() === '') { + endParagraph(); + i += 1; + continue; + } + + const heading = HEADING.exec(line); + if (heading) { + endParagraph(); + const level = Math.min((heading[1] ?? '#').length, 3) as 1 | 2 | 3; + blocks.push({ kind: 'heading', level, content: parseInline(heading[2] ?? '') }); + i += 1; + continue; + } + + if (RULE.test(line)) { + endParagraph(); + blocks.push({ kind: 'rule' }); + i += 1; + continue; + } + + // A table is a row of cells with a row of dashes under it. + const next = lines[i + 1]; + if (line.includes('|') && next !== undefined && next.includes('-') && TABLE_RULE.test(next)) { + const header = cells(line); + if (cells(next).length === header.length) { + endParagraph(); + const rows: Inline[][][] = []; + i += 2; + while ( + i < lines.length && + (lines[i] ?? '').includes('|') && + (lines[i] ?? '').trim() !== '' + ) { + const row = cells(lines[i] ?? ''); + // Short rows are padded and long ones cut, so the grid stays square. + rows.push(header.map((_, column) => parseInline(row[column] ?? ''))); + i += 1; + } + blocks.push({ kind: 'table', header: header.map(parseInline), rows }); + continue; + } + } + + const first = listMatch(line); + if (first) { + endParagraph(); + const items: { indent: number; text: string }[] = []; + while (i < lines.length) { + const current = lines[i] ?? ''; + const item = listMatch(current); + if (item) { + items.push({ indent: item.indent, text: item.text }); + } else if (current.trim() !== '' && /^\s+/.test(current) && items.length > 0) { + // An indented line carries on the item above it. + const last = items[items.length - 1]; + if (last) { + last.text += ` ${current.trim()}`; + } + } else { + break; + } + i += 1; + } + // Depth is the rank of an item's indent among the indents used. + const indents = [...new Set(items.map((item) => item.indent))].sort((a, b) => a - b); + blocks.push({ + kind: 'list', + ordered: first.ordered, + start: first.start, + items: items.map((item) => ({ + depth: Math.min(indents.indexOf(item.indent), 3), + content: parseInline(item.text), + })), + }); + continue; + } + + paragraph.push(line.trim()); + i += 1; + } + endParagraph(); + return blocks; +} diff --git a/src/lib/menu.test.ts b/src/lib/menu.test.ts new file mode 100644 index 0000000..ac3bb07 --- /dev/null +++ b/src/lib/menu.test.ts @@ -0,0 +1,127 @@ +import { describe, expect, it } from 'vitest'; +import { MENUS, commandForKey, shortcutLabel, type KeyPress } from './menu'; + +const press = (key: string, over: Partial = {}): KeyPress => ({ + key, + ctrlKey: false, + metaKey: false, + shiftKey: false, + altKey: false, + ...over, +}); + +describe('the menus', () => { + it('are File, Edit, View, Query, Providers and Help', () => { + expect(MENUS.map((menu) => menu.label)).toEqual([ + 'File', + 'Edit', + 'View', + 'Query', + 'Providers', + 'Help', + ]); + }); + + it('say that reloading credentials restarts the engine', () => { + const labels = MENUS.flatMap((menu) => + menu.entries.flatMap((entry) => + entry.kind === 'command' && entry.id === 'reloadCredentials' ? [entry.label] : [], + ), + ); + expect(labels).toEqual(['Reload Credentials (Restarts the Engine)']); + }); + + it('list each command once', () => { + const ids = MENUS.flatMap((menu) => + menu.entries.flatMap((entry) => (entry.kind === 'command' ? [entry.id] : [])), + ); + expect(new Set(ids).size).toBe(ids.length); + }); + + it('give no two commands the same key', () => { + const keys = MENUS.flatMap((menu) => + menu.entries.flatMap((entry) => + entry.kind === 'command' && entry.shortcut + ? [`${entry.shortcut.shift ? 'shift+' : ''}${entry.shortcut.key}`] + : [], + ), + ); + expect(new Set(keys).size).toBe(keys.length); + }); + + it('offer the log file under Help', () => { + const help = MENUS.find((menu) => menu.label === 'Help'); + const labels = (help?.entries ?? []).flatMap((entry) => + entry.kind === 'command' && entry.id === 'showLog' ? [entry.label] : [], + ); + expect(labels).toEqual(['Show Log File']); + }); + + it('offer the theme as a choice of three under View', () => { + const view = MENUS.find((menu) => menu.label === 'View'); + const choices = (view?.entries ?? []).flatMap((entry) => + entry.kind === 'command' && entry.choice ? [entry.id] : [], + ); + expect(choices).toEqual(['themeSystem', 'themeLight', 'themeDark']); + }); + + it('never start or end with a separator, or have two in a row', () => { + for (const menu of MENUS) { + const kinds = menu.entries.map((entry) => entry.kind); + expect(kinds[0]).toBe('command'); + expect(kinds[kinds.length - 1]).toBe('command'); + kinds.forEach((kind, index) => { + if (kind === 'separator') { + expect(kinds[index + 1]).toBe('command'); + } + }); + } + }); +}); + +describe('shortcutLabel', () => { + it('names the modifier for the platform', () => { + expect(shortcutLabel({ key: 'n' }, false)).toBe('Ctrl+N'); + expect(shortcutLabel({ key: 'n' }, true)).toBe('Cmd+N'); + expect(shortcutLabel({ key: ',' }, false)).toBe('Ctrl+,'); + expect(shortcutLabel({ key: 'p', shift: true }, false)).toBe('Ctrl+Shift+P'); + expect(shortcutLabel({ key: 'Enter' }, false)).toBe('Ctrl+Enter'); + expect(shortcutLabel({ key: 'Enter', shift: true }, true)).toBe('Cmd+Shift+Enter'); + }); +}); + +describe('commandForKey', () => { + it('maps the app shortcuts on Windows', () => { + expect(commandForKey(press('n', { ctrlKey: true }), false)).toBe('newChat'); + expect(commandForKey(press('N', { ctrlKey: true }), false)).toBe('newChat'); + expect(commandForKey(press(',', { ctrlKey: true }), false)).toBe('openSettings'); + expect(commandForKey(press('1', { ctrlKey: true }), false)).toBe('showChat'); + expect(commandForKey(press('2', { ctrlKey: true }), false)).toBe('showExplorer'); + expect(commandForKey(press('3', { ctrlKey: true }), false)).toBe('showActivity'); + expect(commandForKey(press('4', { ctrlKey: true }), false)).toBe('showLibrary'); + expect(commandForKey(press('b', { ctrlKey: true }), false)).toBe('toggleSidebar'); + expect(commandForKey(press('t', { ctrlKey: true }), false)).toBe('newTab'); + expect(commandForKey(press('p', { ctrlKey: true }), false)).toBe('goToResource'); + }); + + it('uses Cmd on macOS, not Ctrl', () => { + expect(commandForKey(press('n', { metaKey: true }), true)).toBe('newChat'); + expect(commandForKey(press('n', { ctrlKey: true }), true)).toBeNull(); + expect(commandForKey(press('n', { metaKey: true }), false)).toBeNull(); + }); + + it('leaves editing keys to the webview', () => { + for (const key of ['z', 'y', 'x', 'c', 'a', 'v']) { + expect(commandForKey(press(key, { ctrlKey: true }), false)).toBeNull(); + } + }); + + it('ignores plain keys and other modifier combinations', () => { + expect(commandForKey(press('n'), false)).toBeNull(); + expect(commandForKey(press('n', { ctrlKey: true, altKey: true }), false)).toBeNull(); + expect(commandForKey(press('n', { ctrlKey: true, shiftKey: true }), false)).toBeNull(); + // Running is the editor's key. It is listed in the menu and left to the editor. + expect(commandForKey(press('Enter', { ctrlKey: true }), false)).toBeNull(); + expect(commandForKey(press('Enter', { ctrlKey: true, shiftKey: true }), false)).toBeNull(); + }); +}); diff --git a/src/lib/menu.ts b/src/lib/menu.ts new file mode 100644 index 0000000..b6868c5 --- /dev/null +++ b/src/lib/menu.ts @@ -0,0 +1,199 @@ +// The app's commands: what the menu bar lists and which keys run them. +// Kept free of React so the mapping can be tested. + +export type CommandId = + | 'newChat' + | 'newTab' + | 'showChat' + | 'showExplorer' + | 'showActivity' + | 'showLibrary' + | 'toggleSidebar' + | 'openSettings' + | 'openModelSettings' + | 'restartEngine' + | 'refreshExplorer' + | 'goToResource' + | 'themeSystem' + | 'themeLight' + | 'themeDark' + | 'run' + | 'runSelection' + | 'addProvider' + | 'checkUpdates' + | 'reloadCredentials' + | 'openDocs' + | 'openQueryLibrary' + | 'reportIssue' + | 'showLog' + | 'about' + | 'exit' + | 'undo' + | 'redo' + | 'cut' + | 'copy' + | 'selectAll'; + +/** A key with the platform's command modifier: Ctrl, or Cmd on macOS. */ +export interface Shortcut { + key: string; + shift?: boolean; + /** + * False for keys the webview already handles, such as Ctrl+C. They are + * listed in the menu so they can be found, and left to the webview. + */ + handled?: boolean; +} + +export type MenuEntry = + | { + kind: 'command'; + id: CommandId; + label: string; + shortcut?: Shortcut; + /** One of a set of which exactly one is chosen. It is drawn with a mark when it is. */ + choice?: boolean; + } + | { kind: 'separator' }; + +export interface Menu { + label: string; + entries: MenuEntry[]; +} + +const command = (id: CommandId, label: string, shortcut?: Shortcut): MenuEntry => ({ + kind: 'command', + id, + label, + ...(shortcut ? { shortcut } : {}), +}); +const choice = (id: CommandId, label: string): MenuEntry => ({ + kind: 'command', + id, + label, + choice: true, +}); +const separator: MenuEntry = { kind: 'separator' }; +const native = (key: string): Shortcut => ({ key, handled: false }); + +export const MENUS: Menu[] = [ + { + label: 'File', + entries: [ + command('newChat', 'New Chat', { key: 'n' }), + separator, + command('openModelSettings', 'Model Backend...'), + command('openSettings', 'Settings...', { key: ',' }), + separator, + command('restartEngine', 'Restart Engine'), + separator, + command('exit', 'Exit'), + ], + }, + { + label: 'Edit', + entries: [ + command('undo', 'Undo', native('z')), + command('redo', 'Redo', native('y')), + separator, + command('cut', 'Cut', native('x')), + command('copy', 'Copy', native('c')), + separator, + command('selectAll', 'Select All', native('a')), + ], + }, + { + label: 'View', + entries: [ + command('showChat', 'Chat', { key: '1' }), + command('showExplorer', 'Explorer', { key: '2' }), + command('showActivity', 'Activity', { key: '3' }), + command('showLibrary', 'Library', { key: '4' }), + separator, + command('goToResource', 'Go to Resource...', { key: 'p' }), + command('refreshExplorer', 'Refresh Explorer'), + separator, + command('toggleSidebar', 'Toggle Sidebar', { key: 'b' }), + separator, + choice('themeSystem', 'Theme: Follow the System'), + choice('themeLight', 'Theme: Light'), + choice('themeDark', 'Theme: Dark'), + ], + }, + { + label: 'Query', + entries: [ + // The editor has these keys. They are listed here so they can be found. + command('run', 'Run', native('Enter')), + command('runSelection', 'Run Selection or Current Statement', { + ...native('Enter'), + shift: true, + }), + separator, + command('newTab', 'New Tab', { key: 't' }), + ], + }, + { + label: 'Providers', + entries: [ + command('addProvider', 'Add from Registry...'), + command('checkUpdates', 'Check for Updates'), + separator, + // On the operator's channel new credentials are read when the engine starts. + command('reloadCredentials', 'Reload Credentials (Restarts the Engine)'), + ], + }, + { + label: 'Help', + entries: [ + command('openDocs', 'Documentation'), + command('openQueryLibrary', 'Query Library'), + command('reportIssue', 'Report an Issue'), + separator, + // Where a failed call of the assistant is written, since the conversation does not list it. + command('showLog', 'Show Log File'), + separator, + command('about', 'About StackQL Workbench'), + ], + }, +]; + +/** How a shortcut is written in the menu, for example Ctrl+N or Cmd+N. */ +export function shortcutLabel(shortcut: Shortcut, isMac: boolean): string { + const key = shortcut.key.length === 1 ? shortcut.key.toUpperCase() : shortcut.key; + return [isMac ? 'Cmd' : 'Ctrl', ...(shortcut.shift ? ['Shift'] : []), key].join('+'); +} + +export interface KeyPress { + key: string; + ctrlKey: boolean; + metaKey: boolean; + shiftKey: boolean; + altKey: boolean; +} + +/** + * The command a key press asks for, if any. Only the app's own shortcuts + * are matched. Editing keys stay with the webview. + */ +export function commandForKey(press: KeyPress, isMac: boolean): CommandId | null { + const modifier = isMac ? press.metaKey && !press.ctrlKey : press.ctrlKey && !press.metaKey; + if (!modifier || press.altKey) { + return null; + } + const key = press.key.toLowerCase(); + for (const menu of MENUS) { + for (const entry of menu.entries) { + if ( + entry.kind === 'command' && + entry.shortcut && + entry.shortcut.handled !== false && + entry.shortcut.key === key && + (entry.shortcut.shift ?? false) === press.shiftKey + ) { + return entry.id; + } + } + } + return null; +} diff --git a/src/lib/results.test.ts b/src/lib/results.test.ts new file mode 100644 index 0000000..8cc9864 --- /dev/null +++ b/src/lib/results.test.ts @@ -0,0 +1,248 @@ +import { describe, expect, it } from 'vitest'; +import type { QueryEvent, RunSummary } from '../host/types'; +import { + applyEvent, + attentionCount, + emptyRun, + failRun, + finishRun, + formatElapsed, + formatRowCount, + gridStatement, + emptyWithNotice, + startRun, + type RunState, +} from './results'; + +function play(events: QueryEvent[], from: RunState = startRun('run-1')): RunState { + return events.reduce(applyEvent, from); +} + +const summary = (over: Partial = {}): RunSummary => ({ + statements: 1, + completed: 1, + failed: false, + abandoned: false, + elapsedMs: 10, + ...over, +}); + +const notice = { + severity: 'NOTICE', + code: '01000', + message: 'a notice level event has occurred', + detail: 'http response status code: 404', +}; + +describe('applyEvent', () => { + it('builds a result from the events of one statement', () => { + const state = play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'SHOW PROVIDERS' } }, + { event: 'columns', data: { index: 0, columns: ['name', 'version'] } }, + { event: 'rows', data: { index: 0, rows: [['github', 'v1']] } }, + { event: 'rows', data: { index: 0, rows: [['homebrew', 'v2']] } }, + { event: 'statementFinished', data: { index: 0, rowCount: 2, elapsedMs: 7 } }, + ]); + + expect(state.total).toBe(1); + expect(state.statements).toHaveLength(1); + const [statement] = state.statements; + expect(statement).toMatchObject({ + sql: 'SHOW PROVIDERS', + status: 'done', + columns: ['name', 'version'], + rowCount: 2, + elapsedMs: 7, + }); + expect(statement?.rows).toEqual([ + ['github', 'v1'], + ['homebrew', 'v2'], + ]); + }); + + it('keeps row batches in order and preserves nulls', () => { + const state = play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'SELECT 1' } }, + { event: 'rows', data: { index: 0, rows: [['a', null]] } }, + { + event: 'rows', + data: { + index: 0, + rows: [ + [null, 'b'], + ['c', 'd'], + ], + }, + }, + ]); + expect(state.statements[0]?.rows).toEqual([ + ['a', null], + [null, 'b'], + ['c', 'd'], + ]); + }); + + it('keeps statements apart', () => { + const state = play([ + { event: 'statementStarted', data: { index: 0, total: 2, sql: 'SHOW VERSION' } }, + { event: 'columns', data: { index: 0, columns: ['version'] } }, + { event: 'rows', data: { index: 0, rows: [['1.0.888']] } }, + { event: 'statementFinished', data: { index: 0, rowCount: 1, elapsedMs: 2 } }, + { event: 'statementStarted', data: { index: 1, total: 2, sql: 'SELEC 1' } }, + { + event: 'statementFailed', + data: { + index: 1, + error: { severity: 'ERROR', code: 'XXUUU', message: 'syntax', connectionLost: false }, + elapsedMs: 1, + }, + }, + ]); + expect(state.statements.map((s) => s.status)).toEqual(['done', 'failed']); + expect(state.statements[0]?.rows).toEqual([['1.0.888']]); + expect(state.statements[1]?.error?.code).toBe('XXUUU'); + expect(state.statements[1]?.rows).toEqual([]); + }); + + it('attaches notices and engine log lines to their statement', () => { + const state = play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'SELECT x' } }, + { event: 'columns', data: { index: 0, columns: ['x'] } }, + { event: 'notice', data: { index: 0, notice } }, + { event: 'engineLog', data: { index: 0, lines: ['line one', 'line two'] } }, + { event: 'statementFinished', data: { index: 0, rowCount: 0, elapsedMs: 80 } }, + ]); + expect(state.statements[0]?.notices).toEqual([notice]); + expect(state.statements[0]?.engineLog).toEqual(['line one', 'line two']); + }); + + it('ignores an event for a statement that never started', () => { + const state = play([{ event: 'rows', data: { index: 3, rows: [['x']] } }]); + expect(state.statements).toEqual([]); + }); + + it('does not mutate the previous state', () => { + const before = play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'SELECT 1' } }, + { event: 'rows', data: { index: 0, rows: [['a']] } }, + ]); + const rowsBefore = before.statements[0]?.rows; + const after = applyEvent(before, { event: 'rows', data: { index: 0, rows: [['b']] } }); + expect(rowsBefore).toEqual([['a']]); + expect(after.statements[0]?.rows).toEqual([['a'], ['b']]); + }); +}); + +describe('finishRun and failRun', () => { + it('marks the run as finished', () => { + const state = finishRun( + play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'SELECT 1' } }, + { event: 'statementFinished', data: { index: 0, rowCount: 0, elapsedMs: 1 } }, + ]), + summary(), + ); + expect(state.running).toBe(false); + expect(state.summary?.completed).toBe(1); + }); + + it('marks the statement the operator stopped waiting for as abandoned', () => { + const state = finishRun( + play([{ event: 'statementStarted', data: { index: 0, total: 1, sql: 'SELECT slow' } }]), + summary({ completed: 0, abandoned: true }), + ); + expect(state.statements[0]?.status).toBe('abandoned'); + }); + + it('records a failure of the host call', () => { + const state = failRun(startRun('run-1'), { + kind: 'engineNotRunning', + message: 'The engine is not running.', + }); + expect(state.running).toBe(false); + expect(state.hostError?.kind).toBe('engineNotRunning'); + }); +}); + +describe('gridStatement', () => { + it('is null when nothing has run', () => { + expect(gridStatement(emptyRun)).toBeNull(); + }); + + it('prefers the last statement that produced a result set', () => { + const state = play([ + { event: 'statementStarted', data: { index: 0, total: 2, sql: 'SHOW PROVIDERS' } }, + { event: 'columns', data: { index: 0, columns: ['name'] } }, + { event: 'statementFinished', data: { index: 0, rowCount: 0, elapsedMs: 1 } }, + { event: 'statementStarted', data: { index: 1, total: 2, sql: 'REGISTRY PULL github' } }, + { event: 'statementFinished', data: { index: 1, rowCount: 0, elapsedMs: 900 } }, + ]); + expect(gridStatement(state)?.sql).toBe('SHOW PROVIDERS'); + }); + + it('falls back to the last statement when none has columns', () => { + const state = play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'REGISTRY PULL github' } }, + ]); + expect(gridStatement(state)?.sql).toBe('REGISTRY PULL github'); + }); +}); + +describe('emptyWithNotice', () => { + const base = play([ + { event: 'statementStarted', data: { index: 0, total: 1, sql: 'SELECT x' } }, + { event: 'columns', data: { index: 0, columns: ['x'] } }, + ]); + + it('is true for a successful empty result with a notice', () => { + const state = play( + [ + { event: 'notice', data: { index: 0, notice } }, + { event: 'statementFinished', data: { index: 0, rowCount: 0, elapsedMs: 80 } }, + ], + base, + ); + const [statement] = state.statements; + expect(statement && emptyWithNotice(statement)).toBe(true); + expect(attentionCount(state)).toBe(1); + }); + + it('is false for a plain empty result', () => { + const state = play( + [{ event: 'statementFinished', data: { index: 0, rowCount: 0, elapsedMs: 3 } }], + base, + ); + const [statement] = state.statements; + expect(statement && emptyWithNotice(statement)).toBe(false); + expect(attentionCount(state)).toBe(0); + }); + + it('is false when rows came back with the notice', () => { + const state = play( + [ + { event: 'rows', data: { index: 0, rows: [['wget']] } }, + { event: 'notice', data: { index: 0, notice } }, + { event: 'statementFinished', data: { index: 0, rowCount: 1, elapsedMs: 80 } }, + ], + base, + ); + const [statement] = state.statements; + expect(statement && emptyWithNotice(statement)).toBe(false); + }); +}); + +describe('formatting', () => { + it('formats elapsed time', () => { + expect(formatElapsed(0)).toBe('0 ms'); + expect(formatElapsed(999)).toBe('999 ms'); + expect(formatElapsed(1234)).toBe('1.23 s'); + expect(formatElapsed(12_345)).toBe('12.3 s'); + expect(formatElapsed(125_000)).toBe('2 min 5 s'); + }); + + it('formats row counts', () => { + expect(formatRowCount(0)).toBe('0 rows'); + expect(formatRowCount(1)).toBe('1 row'); + expect(formatRowCount(12_345)).toBe('12,345 rows'); + }); +}); diff --git a/src/lib/results.ts b/src/lib/results.ts new file mode 100644 index 0000000..49643af --- /dev/null +++ b/src/lib/results.ts @@ -0,0 +1,230 @@ +// The state of a run in the results pane, built up from the events the host +// streams. Pure functions, so the mapping can be tested without a host. + +import type { HostError, Notice, QueryError, QueryEvent, Row, RunSummary } from '../host/types'; + +export type StatementStatus = 'running' | 'done' | 'failed' | 'abandoned'; + +export interface StatementResult { + index: number; + sql: string; + status: StatementStatus; + /** Null until the engine has described the result. Some statements never do. */ + columns: string[] | null; + rows: Row[]; + /** Set when the statement finishes. The engine does not report a count, the host counts. */ + rowCount: number | null; + elapsedMs: number | null; + notices: Notice[]; + /** Lines the engine wrote to stderr while the statement ran. */ + engineLog: string[]; + error: QueryError | null; +} + +export interface RunState { + runId: string | null; + /** Who produced it: the operator from the editor, or the assistant. */ + origin: 'operator' | 'agent'; + running: boolean; + /** Statements found in the text. Known once the first one starts. */ + total: number; + statements: StatementResult[]; + summary: RunSummary | null; + /** Set when the host call itself failed, for example because the engine is down. */ + hostError: HostError | null; +} + +export const emptyRun: RunState = { + runId: null, + origin: 'operator', + running: false, + total: 0, + statements: [], + summary: null, + hostError: null, +}; + +export function startRun(runId: string): RunState { + return { ...emptyRun, runId, running: true }; +} + +function newStatement(index: number, sql: string): StatementResult { + return { + index, + sql, + status: 'running', + columns: null, + rows: [], + rowCount: null, + elapsedMs: null, + notices: [], + engineLog: [], + error: null, + }; +} + +function update( + state: RunState, + index: number, + change: (statement: StatementResult) => StatementResult, +): RunState { + if (!state.statements.some((s) => s.index === index)) { + // An event for a statement that never started. Nothing to attach it to. + return state; + } + return { + ...state, + statements: state.statements.map((s) => (s.index === index ? change(s) : s)), + }; +} + +/** + * A finished run made from a row result the assistant produced, so that it + * shows in the same grid as the operator's own results. + */ +export function agentRun( + id: string, + sql: string, + columns: string[], + rows: Row[], + elapsedMs: number, + engineNotes: string[], +): RunState { + const statement: StatementResult = { + ...newStatement(0, sql), + status: 'done', + columns, + rows, + rowCount: rows.length, + elapsedMs, + // Shown the same way as a provider's message on the operator's channel. + notices: engineNotes.map((note) => ({ + severity: 'NOTICE', + code: '', + message: note, + detail: note, + })), + }; + return { ...emptyRun, runId: id, origin: 'agent', total: 1, statements: [statement] }; +} + +/** Applies one host event. */ +export function applyEvent(state: RunState, event: QueryEvent): RunState { + switch (event.event) { + case 'statementStarted': + return { + ...state, + total: event.data.total, + statements: [...state.statements, newStatement(event.data.index, event.data.sql)], + }; + case 'columns': + return update(state, event.data.index, (s) => ({ ...s, columns: event.data.columns })); + case 'rows': + return update(state, event.data.index, (s) => ({ + ...s, + rows: s.rows.concat(event.data.rows), + })); + case 'notice': + return update(state, event.data.index, (s) => ({ + ...s, + notices: [...s.notices, event.data.notice], + })); + case 'engineLog': + return update(state, event.data.index, (s) => ({ + ...s, + engineLog: s.engineLog.concat(event.data.lines), + })); + case 'statementFinished': + return update(state, event.data.index, (s) => ({ + ...s, + status: 'done', + rowCount: event.data.rowCount, + elapsedMs: event.data.elapsedMs, + })); + case 'statementFailed': + return update(state, event.data.index, (s) => ({ + ...s, + status: 'failed', + error: event.data.error, + elapsedMs: event.data.elapsedMs, + })); + } +} + +/** Applies the outcome of the host call that ran the statements. */ +export function finishRun(state: RunState, summary: RunSummary): RunState { + return { + ...state, + running: false, + summary, + // A statement still marked running was the one the operator stopped waiting for. + statements: state.statements.map((s) => + s.status === 'running' ? { ...s, status: summary.abandoned ? 'abandoned' : 'failed' } : s, + ), + }; +} + +/** Applies a failure of the host call itself. */ +export function failRun(state: RunState, error: HostError): RunState { + return { + ...state, + running: false, + hostError: error, + statements: state.statements.map((s) => + s.status === 'running' ? { ...s, status: 'failed' } : s, + ), + }; +} + +/** + * The statement whose result the grid should show: the last one that + * produced a result set, or failing that the last one. + */ +export function gridStatement(state: RunState): StatementResult | null { + for (let i = state.statements.length - 1; i >= 0; i -= 1) { + const statement = state.statements[i]; + if (statement?.columns && statement.columns.length > 0) { + return statement; + } + } + return state.statements.at(-1) ?? null; +} + +/** + * True when a statement succeeded with no rows and the engine attached a + * notice, which carries what the provider answered. That can be an ordinary + * answer, such as "not found" for a lookup of one thing, or a call that did + * not succeed. The engine does not tell the two apart, and neither does + * this. The operator is shown the message. See docs/spike-pgwire.md. + */ +export function emptyWithNotice(statement: StatementResult): boolean { + return statement.status === 'done' && statement.rows.length === 0 && statement.notices.length > 0; +} + +/** Number of things in the messages area that deserve attention. */ +export function attentionCount(state: RunState): number { + let count = state.hostError ? 1 : 0; + for (const statement of state.statements) { + if (statement.error) { + count += 1; + } + count += statement.notices.length; + } + return count; +} + +export function formatElapsed(ms: number): string { + if (ms < 1000) { + return `${ms} ms`; + } + if (ms < 60_000) { + return `${(ms / 1000).toFixed(ms < 10_000 ? 2 : 1)} s`; + } + const minutes = Math.floor(ms / 60_000); + const seconds = Math.round((ms % 60_000) / 1000); + return `${minutes} min ${seconds} s`; +} + +export function formatRowCount(count: number): string { + return `${count.toLocaleString('en-US')} ${count === 1 ? 'row' : 'rows'}`; +} diff --git a/src/lib/sortRows.test.ts b/src/lib/sortRows.test.ts new file mode 100644 index 0000000..3fc2da4 --- /dev/null +++ b/src/lib/sortRows.test.ts @@ -0,0 +1,125 @@ +import { describe, expect, it } from 'vitest'; +import type { Row } from '../host/types'; +import { cellNumber, nextSort, sortRows } from './sortRows'; + +const column = (rows: Row[], index = 0) => rows.map((row) => row[index]); + +describe('nextSort', () => { + it('goes ascending, descending, then back to the order of arrival', () => { + const first = nextSort(null, 2); + expect(first).toEqual({ column: 2, direction: 'asc' }); + const second = nextSort(first, 2); + expect(second).toEqual({ column: 2, direction: 'desc' }); + expect(nextSort(second, 2)).toBeNull(); + }); + + it('starts again on another column', () => { + expect(nextSort({ column: 2, direction: 'desc' }, 0)).toEqual({ column: 0, direction: 'asc' }); + }); +}); + +describe('cellNumber', () => { + it('reads numbers and nothing else', () => { + expect(cellNumber('42')).toBe(42); + expect(cellNumber(' -3.5 ')).toBe(-3.5); + expect(cellNumber('1e3')).toBe(1000); + expect(cellNumber('.5')).toBe(0.5); + expect(cellNumber('')).toBeNull(); + expect(cellNumber(null)).toBeNull(); + expect(cellNumber('2026-11')).toBeNull(); + expect(cellNumber('0x10')).toBeNull(); + expect(cellNumber('true')).toBeNull(); + expect(cellNumber('Infinity')).toBeNull(); + }); +}); + +describe('sortRows', () => { + const rows: Row[] = [['10'], ['9'], ['100'], ['-1']]; + + it('returns the rows as they are when no sort is set', () => { + expect(sortRows(rows, null)).toBe(rows); + }); + + it('orders numbers by size, not as text', () => { + expect(column(sortRows(rows, { column: 0, direction: 'asc' }))).toEqual([ + '-1', + '9', + '10', + '100', + ]); + expect(column(sortRows(rows, { column: 0, direction: 'desc' }))).toEqual([ + '100', + '10', + '9', + '-1', + ]); + }); + + it('does not change the rows it was given', () => { + sortRows(rows, { column: 0, direction: 'asc' }); + expect(column(rows)).toEqual(['10', '9', '100', '-1']); + }); + + it('orders words without regard to case, and digits inside them by size', () => { + const names: Row[] = [['vm-10'], ['Vm-2'], ['alpha'], ['Beta']]; + expect(column(sortRows(names, { column: 0, direction: 'asc' }))).toEqual([ + 'alpha', + 'Beta', + 'Vm-2', + 'vm-10', + ]); + }); + + it('orders dates written the ISO way', () => { + const dates: Row[] = [['2026-11-16T01:40:36Z'], ['2023-01-05T00:00:00Z'], ['2026-03-01']]; + expect(column(sortRows(dates, { column: 0, direction: 'asc' }))).toEqual([ + '2023-01-05T00:00:00Z', + '2026-03-01', + '2026-11-16T01:40:36Z', + ]); + }); + + it('keeps empty values last in both directions', () => { + const mixed: Row[] = [[null], ['b'], [''], ['a'], ['3']]; + expect(column(sortRows(mixed, { column: 0, direction: 'asc' }))).toEqual([ + '3', + 'a', + 'b', + null, + '', + ]); + expect(column(sortRows(mixed, { column: 0, direction: 'desc' }))).toEqual([ + 'b', + 'a', + '3', + null, + '', + ]); + }); + + it('keeps the order of arrival among rows that compare equal', () => { + const tied: Row[] = [ + ['open', 'first'], + ['closed', 'second'], + ['open', 'third'], + ['closed', 'fourth'], + ]; + expect(column(sortRows(tied, { column: 0, direction: 'asc' }), 1)).toEqual([ + 'second', + 'fourth', + 'first', + 'third', + ]); + expect(column(sortRows(tied, { column: 0, direction: 'desc' }), 1)).toEqual([ + 'first', + 'third', + 'second', + 'fourth', + ]); + }); + + it('treats a column a row does not have as empty', () => { + const ragged: Row[] = [['a'], ['b', '1'], ['c', '0']]; + expect(column(sortRows(ragged, { column: 1, direction: 'asc' }))).toEqual(['c', 'b', 'a']); + }); +}); diff --git a/src/lib/sortRows.ts b/src/lib/sortRows.ts new file mode 100644 index 0000000..6277edb --- /dev/null +++ b/src/lib/sortRows.ts @@ -0,0 +1,87 @@ +// Sorting a result set in the webview, by one column. The engine sends every +// value as text, so the order is worked out from the text: numbers by size, +// everything else as words. + +import type { Row } from '../host/types'; + +export type SortDirection = 'asc' | 'desc'; + +export interface SortState { + /** The position of the column. Names can repeat, positions cannot. */ + column: number; + direction: SortDirection; +} + +/** + * What a click on a column header asks for: ascending, then descending, + * then the order the rows arrived in. + */ +export function nextSort(current: SortState | null, column: number): SortState | null { + if (current?.column !== column) { + return { column, direction: 'asc' }; + } + return current.direction === 'asc' ? { column, direction: 'desc' } : null; +} + +const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/; + +/** The number a cell holds, or null when it is not one. */ +export function cellNumber(value: string | null): number | null { + if (value === null) { + return null; + } + const text = value.trim(); + if (!NUMBER.test(text)) { + return null; + } + const parsed = Number(text); + return Number.isFinite(parsed) ? parsed : null; +} + +const collator = new Intl.Collator('en', { numeric: true, sensitivity: 'base' }); + +type Key = { rank: 0; number: number } | { rank: 1; text: string } | { rank: 2 }; + +/** A NULL and an empty value have nothing to order by, so they go last. */ +function sortKey(value: string | null | undefined): Key { + if (value === null || value === undefined || value.trim() === '') { + return { rank: 2 }; + } + const number = cellNumber(value); + return number === null ? { rank: 1, text: value } : { rank: 0, number }; +} + +function compareKeys(a: Key, b: Key): number { + if (a.rank !== b.rank) { + return a.rank - b.rank; + } + if (a.rank === 0 && b.rank === 0) { + return a.number - b.number; + } + if (a.rank === 1 && b.rank === 1) { + return collator.compare(a.text, b.text); + } + return 0; +} + +/** + * The rows in the order asked for. Numbers come before words, and both + * before empty values, which stay last in either direction. Rows that + * compare equal keep the order they arrived in. The input is not changed. + */ +export function sortRows(rows: Row[], sort: SortState | null): Row[] { + if (sort === null) { + return rows; + } + const flip = sort.direction === 'desc' ? -1 : 1; + return rows + .map((row, index) => ({ row, index, key: sortKey(row[sort.column]) })) + .sort((a, b) => { + // Empty values are last whichever way the rest runs. + if (a.key.rank === 2 || b.key.rank === 2) { + return a.key.rank - b.key.rank || a.index - b.index; + } + return flip * compareKeys(a.key, b.key) || a.index - b.index; + }) + .map((entry) => entry.row); +} diff --git a/src/lib/tabs.test.ts b/src/lib/tabs.test.ts new file mode 100644 index 0000000..d540f29 --- /dev/null +++ b/src/lib/tabs.test.ts @@ -0,0 +1,131 @@ +import { describe, expect, it } from 'vitest'; +import { + activateTab, + addTab, + closeTab, + restoreTabs, + saveTabs, + singleTab, + stateOf, + titleFor, +} from './tabs'; + +const start = () => stateOf(singleTab('SHOW PROVIDERS;')); + +describe('titleFor', () => { + it('names an empty tab by its number', () => { + expect(titleFor('', 3)).toBe('Query 3'); + expect(titleFor('-- only a comment\n\n', 4)).toBe('Query 4'); + }); + + it('uses the start of the first statement, on one line', () => { + expect(titleFor('-- note\nSHOW PROVIDERS;', 1)).toBe('SHOW PROVIDERS'); + const title = titleFor("SELECT login FROM github.orgs.orgs WHERE org = 'stackql';", 1); + expect(title.length).toBeLessThanOrEqual(28); + expect(title.endsWith('...')).toBe(true); + expect(title.startsWith('SELECT login FROM')).toBe(true); + }); +}); + +describe('restoreTabs', () => { + it('starts with one tab holding the fallback text', () => { + const saved = restoreTabs(null, 'hello'); + expect(saved.tabs).toEqual([{ id: 'tab-1', title: 'Query 1', text: 'hello' }]); + expect(saved.activeId).toBe('tab-1'); + }); + + it('gives back what was saved', () => { + let state = start(); + state = addTab(state, 'SELECT 1;').state; + const texts: Record = { 'tab-1': 'one', 'tab-2': 'two' }; + const saved = restoreTabs( + saveTabs(state, (id) => texts[id] ?? ''), + 'unused', + ); + expect(saved.tabs.map((t) => t.text)).toEqual(['one', 'two']); + expect(saved.activeId).toBe('tab-2'); + expect(saved.next).toBe(3); + }); + + it('falls back to one tab when the saved value is damaged', () => { + for (const bad of ['{ not json', 'null', '{}', '{"tabs":[]}', '{"tabs":[{"id":1}]}']) { + expect(restoreTabs(bad, 'kept').tabs).toEqual([ + { id: 'tab-1', title: 'Query 1', text: 'kept' }, + ]); + } + }); + + it('does not accept two tabs with one id', () => { + const twice = JSON.stringify({ + tabs: [ + { id: 'a', title: 'A', text: '' }, + { id: 'a', title: 'B', text: '' }, + ], + activeId: 'a', + next: 3, + }); + expect(restoreTabs(twice, 'kept').tabs).toHaveLength(1); + }); + + it('repairs an active id that is not among the tabs and a counter that is too low', () => { + const odd = JSON.stringify({ + tabs: [ + { id: 'tab-5', title: 'A', text: '' }, + { id: 'tab-9', title: 'B', text: '' }, + ], + activeId: 'gone', + next: 1, + }); + const saved = restoreTabs(odd, ''); + expect(saved.activeId).toBe('tab-5'); + expect(saved.next).toBe(3); + }); +}); + +describe('addTab', () => { + it('opens at the end, in front, with a new id', () => { + const { state, id } = addTab(start(), 'SELECT 1;'); + expect(state.tabs.map((t) => t.id)).toEqual(['tab-1', 'tab-2']); + expect(id).toBe('tab-2'); + expect(state.activeId).toBe('tab-2'); + expect(state.tabs[1]?.title).toBe('SELECT 1'); + }); + + it('never reuses an id after a tab is closed', () => { + let state = addTab(start()).state; + state = closeTab(state, 'tab-2'); + expect(addTab(state).id).toBe('tab-3'); + }); +}); + +describe('closeTab', () => { + const three = () => addTab(addTab(start()).state).state; + + it('brings the neighbour to the front when the front tab closes', () => { + let state = activateTab(three(), 'tab-2'); + state = closeTab(state, 'tab-2'); + expect(state.tabs.map((t) => t.id)).toEqual(['tab-1', 'tab-3']); + expect(state.activeId).toBe('tab-3'); + // Closing the last one in the row falls back to the one before it. + state = closeTab(state, 'tab-3'); + expect(state.activeId).toBe('tab-1'); + }); + + it('leaves the front tab alone when another closes', () => { + const state = closeTab(three(), 'tab-1'); + expect(state.activeId).toBe('tab-3'); + }); + + it('replaces the last tab with an empty one', () => { + const state = closeTab(start(), 'tab-1'); + expect(state.tabs).toHaveLength(1); + expect(state.tabs[0]?.id).toBe('tab-2'); + expect(state.activeId).toBe('tab-2'); + }); + + it('ignores an id it does not have', () => { + const state = three(); + expect(closeTab(state, 'nope')).toBe(state); + expect(activateTab(state, 'nope')).toBe(state); + }); +}); diff --git a/src/lib/tabs.ts b/src/lib/tabs.ts new file mode 100644 index 0000000..61d6857 --- /dev/null +++ b/src/lib/tabs.ts @@ -0,0 +1,130 @@ +// Editor tabs: which buffers are open and which one is in front. Pure, so +// it can be tested. The text of a buffer lives in its editor and is only +// passed through here to be saved and restored. + +export interface Tab { + id: string; + title: string; +} + +export interface TabsState { + tabs: Tab[]; + activeId: string; + /** Counter for ids and for "Query N" titles. */ + next: number; +} + +/** What is written to storage: the tabs with their text. */ +export interface SavedTabs { + tabs: { id: string; title: string; text: string }[]; + activeId: string; + next: number; +} + +const TITLE_LENGTH = 28; + +/** A short name for a tab: the start of its first statement, or "Query N". */ +export function titleFor(text: string, number: number): string { + const line = text + .split('\n') + .map((l) => l.trim()) + .find((l) => l !== '' && !l.startsWith('--')); + if (!line) { + return `Query ${number}`; + } + const flat = line.replace(/\s+/g, ' ').replace(/;$/, ''); + return flat.length > TITLE_LENGTH ? `${flat.slice(0, TITLE_LENGTH - 3).trimEnd()}...` : flat; +} + +/** One tab holding `text`. The state a first run starts from. */ +export function singleTab(text: string): SavedTabs { + return { tabs: [{ id: 'tab-1', title: 'Query 1', text }], activeId: 'tab-1', next: 2 }; +} + +/** + * Reads what was saved. Anything that is not the expected shape gives one + * tab holding `fallbackText`, so a damaged entry never loses the editor. + */ +export function restoreTabs(saved: string | null, fallbackText: string): SavedTabs { + if (saved === null) { + return singleTab(fallbackText); + } + try { + const parsed = JSON.parse(saved) as Partial | null; + const tabs = Array.isArray(parsed?.tabs) + ? parsed.tabs.filter( + (tab): tab is SavedTabs['tabs'][number] => + typeof tab === 'object' && + typeof tab.id === 'string' && + typeof tab.title === 'string' && + typeof tab.text === 'string', + ) + : []; + if (tabs.length === 0 || new Set(tabs.map((t) => t.id)).size !== tabs.length) { + return singleTab(fallbackText); + } + const activeId = tabs.some((t) => t.id === parsed?.activeId) + ? (parsed?.activeId as string) + : (tabs[0]?.id ?? 'tab-1'); + const next = + typeof parsed?.next === 'number' && parsed.next > tabs.length ? parsed.next : tabs.length + 1; + return { tabs, activeId, next }; + } catch { + return singleTab(fallbackText); + } +} + +export function stateOf(saved: SavedTabs): TabsState { + return { + tabs: saved.tabs.map(({ id, title }) => ({ id, title })), + activeId: saved.activeId, + next: saved.next, + }; +} + +/** Opens a new tab at the end and brings it to the front. Returns its id too. */ +export function addTab(state: TabsState, text = ''): { state: TabsState; id: string } { + const id = `tab-${state.next}`; + return { + id, + state: { + tabs: [...state.tabs, { id, title: titleFor(text, state.next) }], + activeId: id, + next: state.next + 1, + }, + }; +} + +/** + * Closes a tab. If it was in front, its neighbour comes to the front. The + * last tab cannot be closed away: an empty one takes its place. + */ +export function closeTab(state: TabsState, id: string): TabsState { + const index = state.tabs.findIndex((tab) => tab.id === id); + if (index < 0) { + return state; + } + const remaining = state.tabs.filter((tab) => tab.id !== id); + if (remaining.length === 0) { + return addTab({ ...state, tabs: [] }).state; + } + const activeId = + state.activeId === id + ? (remaining[Math.min(index, remaining.length - 1)]?.id ?? state.activeId) + : state.activeId; + return { ...state, tabs: remaining, activeId }; +} + +export function activateTab(state: TabsState, id: string): TabsState { + return state.tabs.some((tab) => tab.id === id) ? { ...state, activeId: id } : state; +} + +/** Puts the tabs and their text into the form that is saved. */ +export function saveTabs(state: TabsState, text: (id: string) => string): string { + const saved: SavedTabs = { + tabs: state.tabs.map((tab) => ({ ...tab, text: text(tab.id) })), + activeId: state.activeId, + next: state.next, + }; + return JSON.stringify(saved); +} diff --git a/src/lib/theme.test.ts b/src/lib/theme.test.ts new file mode 100644 index 0000000..f04d1f0 --- /dev/null +++ b/src/lib/theme.test.ts @@ -0,0 +1,124 @@ +import { describe, expect, it } from 'vitest'; +// The tokens, read from the stylesheet the app ships. +import css from '../styles.css?raw'; +import { contrastRatio, parseThemeChoice, resolveTheme } from './theme'; + +describe('the theme choice', () => { + it('follows the system unless the operator chose', () => { + expect(resolveTheme('system', true)).toBe('dark'); + expect(resolveTheme('system', false)).toBe('light'); + expect(resolveTheme('light', true)).toBe('light'); + expect(resolveTheme('dark', false)).toBe('dark'); + }); + + it('reads what was stored, and falls back to the system', () => { + expect(parseThemeChoice('dark')).toBe('dark'); + expect(parseThemeChoice('light')).toBe('light'); + expect(parseThemeChoice('system')).toBe('system'); + expect(parseThemeChoice(null)).toBe('system'); + expect(parseThemeChoice('purple')).toBe('system'); + }); +}); + +describe('contrastRatio', () => { + it('matches the known values', () => { + expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 5); + expect(contrastRatio('#ffffff', '#ffffff')).toBeCloseTo(1, 5); + // The usual example of the lightest grey that passes AA on white. + expect(contrastRatio('#767676', '#ffffff')).toBeGreaterThanOrEqual(4.5); + expect(contrastRatio('#777777', '#ffffff')).toBeLessThan(4.5); + }); +}); + +function block(start: string): string { + const at = css.indexOf(start); + if (at < 0) { + throw new Error(`No ${start} block in styles.css`); + } + return css.slice(at, css.indexOf('}', at)); +} + +function tokens(text: string): Record { + const found: Record = {}; + for (const match of text.matchAll(/--([a-z][a-z0-9-]*):\s*(#[0-9a-fA-F]{6})\s*;/g)) { + if (match[1] && match[2]) { + found[match[1]] = match[2]; + } + } + return found; +} + +const light = { ...tokens(block('@theme {')), ...tokens(block(':root {')) }; +const dark = { ...light, ...tokens(block(":root[data-theme='dark'] {")) }; + +/** Text and the surfaces it is drawn on. AA asks for 4.5 to 1. */ +const PAIRS: [string, string[]][] = [ + ['color-ink', ['color-surface', 'color-surface-alt', 'color-surface-sunken']], + ['color-ink-muted', ['color-surface', 'color-surface-alt', 'color-surface-sunken']], + ['color-accent', ['color-surface', 'color-surface-alt', 'color-surface-sunken']], + ['color-danger', ['color-surface', 'color-surface-alt']], + ['color-warn', ['color-surface', 'color-surface-alt']], + ['color-ok', ['color-surface', 'color-surface-alt']], + ['color-on-brand', ['color-brand', 'color-brand-dark', 'color-brand-light']], + ['syntax-keyword', ['color-surface']], + ['syntax-string', ['color-surface']], + ['syntax-number', ['color-surface']], + ['syntax-comment', ['color-surface']], + ['syntax-type', ['color-surface']], + ['syntax-func', ['color-surface']], +]; + +describe.each([ + ['light', light], + ['dark', dark], +])('the %s theme', (_name, theme) => { + it('defines every token the pairs name', () => { + for (const [text, surfaces] of PAIRS) { + for (const token of [text, ...surfaces]) { + expect(theme[token], token).toMatch(/^#[0-9a-fA-F]{6}$/); + } + } + }); + + it.each(PAIRS.flatMap(([text, surfaces]) => surfaces.map((surface) => [text, surface])))( + 'draws %s on %s at 4.5 to 1 or better', + (text, surface) => { + const ratio = contrastRatio(theme[text] ?? '', theme[surface] ?? ''); + expect( + ratio, + `${theme[text]} on ${theme[surface]} is ${ratio.toFixed(2)}`, + ).toBeGreaterThanOrEqual(4.5); + }, + ); +}); + +/** The series of a chart, in their fixed order. */ +const CHART = Array.from({ length: 8 }, (_, index) => `chart-${index + 1}`); + +describe.each([ + ['light', light, 2], + ['dark', dark, 3], +])('the chart colours of the %s theme', (_name, theme, floor) => { + it('are eight, each of them different', () => { + const values = CHART.map((token) => theme[token]?.toLowerCase()); + for (const value of values) { + expect(value).toMatch(/^#[0-9a-f]{6}$/); + } + expect(new Set(values).size).toBe(CHART.length); + }); + + // A mark is not text, so the bar is lower than for ink. The light theme + // has three steps under 3 to 1, which the table beside every chart is + // there to make up for. None may fade into the surface. + it.each(CHART)(`draws %s on the surface at ${floor} to 1 or better`, (token) => { + const ratio = contrastRatio(theme[token] ?? '', theme['color-surface'] ?? ''); + expect(ratio, `${theme[token]} is ${ratio.toFixed(2)}`).toBeGreaterThanOrEqual(floor); + }); +}); + +describe('the brand colour', () => { + it('is Classic Blue in both themes, with no second blue beside it', () => { + expect(light['color-brand']?.toLowerCase()).toBe('#0f4c81'); + expect(dark['color-brand']?.toLowerCase()).toBe('#0f4c81'); + }); +}); diff --git a/src/lib/theme.ts b/src/lib/theme.ts new file mode 100644 index 0000000..87587f7 --- /dev/null +++ b/src/lib/theme.ts @@ -0,0 +1,47 @@ +// Which theme the app shows, and the contrast between two colours. +// The colours themselves are tokens in src/styles.css. + +/** What the operator chose under View. */ +export type ThemeChoice = 'system' | 'light' | 'dark'; +/** What is drawn. */ +export type Theme = 'light' | 'dark'; + +export const THEME_KEY = 'workbench.theme'; + +/** Reads a stored choice. Anything unknown follows the system. */ +export function parseThemeChoice(stored: string | null): ThemeChoice { + return stored === 'light' || stored === 'dark' ? stored : 'system'; +} + +/** The theme to draw: the operator's choice, or the system's when they left it alone. */ +export function resolveTheme(choice: ThemeChoice, systemDark: boolean): Theme { + if (choice === 'system') { + return systemDark ? 'dark' : 'light'; + } + return choice; +} + +function channels(hex: string): [number, number, number] { + const match = /^#([0-9a-f]{6})$/i.exec(hex.trim()); + if (!match?.[1]) { + throw new Error(`Not a six digit colour: ${hex}`); + } + const value = Number.parseInt(match[1], 16); + return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff]; +} + +/** Relative luminance, as WCAG 2 defines it. */ +function luminance(hex: string): number { + const [r, g, b] = channels(hex).map((channel) => { + const share = channel / 255; + return share <= 0.03928 ? share / 12.92 : ((share + 0.055) / 1.055) ** 2.4; + }); + return 0.2126 * (r ?? 0) + 0.7152 * (g ?? 0) + 0.0722 * (b ?? 0); +} + +/** The WCAG 2 contrast ratio of two colours, from 1 to 21. */ +export function contrastRatio(first: string, second: string): number { + const a = luminance(first); + const b = luminance(second); + return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05); +} diff --git a/src/main.tsx b/src/main.tsx new file mode 100644 index 0000000..e05ec52 --- /dev/null +++ b/src/main.tsx @@ -0,0 +1,18 @@ +import { StrictMode } from 'react'; +import { createRoot } from 'react-dom/client'; +import { App } from './App'; +import { applyStoredTheme } from './state/useTheme'; +import './styles.css'; + +applyStoredTheme(); + +const root = document.getElementById('root'); +if (!root) { + throw new Error('Missing #root element'); +} + +createRoot(root).render( + + + , +); diff --git a/src/panes/activity/ActivityPane.tsx b/src/panes/activity/ActivityPane.tsx new file mode 100644 index 0000000..ca41cda --- /dev/null +++ b/src/panes/activity/ActivityPane.tsx @@ -0,0 +1,286 @@ +import { useEffect, useMemo, useState } from 'react'; +import { host, toHostError, type Activity } from '../../host'; +import { + NO_FILTER, + OUTCOME_CHOICES, + activityJsonl, + activityRows, + filterActivity, + formatTime, + type ActivityFilter, + type ActivityRow, +} from '../../lib/activity'; +import { formatElapsed } from '../../lib/results'; +import { IconButton } from '../../ui/IconButton'; +import { Download, OpenInEditor, Refresh, Spinner } from '../../ui/icons'; + +const TONE: Record = { + ok: 'text-ok', + warn: 'text-warn', + error: 'text-danger', + muted: 'text-ink-muted', +}; + +/** Time, actor, mode, statement, duration, rows, outcome, and the row's action. */ +const COLUMNS = + 'grid grid-cols-[104px_48px_86px_minmax(0,1fr)_72px_52px_minmax(96px,170px)_24px] gap-x-3 px-2'; + +const two = (value: number) => String(value).padStart(2, '0'); + +function exportName(now: Date): string { + const day = `${now.getFullYear()}${two(now.getMonth() + 1)}${two(now.getDate())}`; + return `stackql-activity-${day}-${two(now.getHours())}${two(now.getMinutes())}${two(now.getSeconds())}.jsonl`; +} + +interface ActivityPaneProps { + /** Changing this value reloads the list. */ + refreshToken: number; + onOpenInEditor: (sql: string) => void; +} + +/** + * What was run, by whom. Statements the operator ran come from the app's + * history. What the agent did comes from the engine's own audit log. + */ +export function ActivityPane({ refreshToken, onOpenInEditor }: ActivityPaneProps) { + const [activity, setActivity] = useState(null); + const [error, setError] = useState(null); + const [manual, setManual] = useState(0); + const [filter, setFilter] = useState(NO_FILTER); + // What the last export did. + const [note, setNote] = useState<{ text: string; failed: boolean } | null>(null); + // The request that has come back. Loading is any other request. + const [settled, setSettled] = useState(null); + const request = `${refreshToken}:${manual}`; + const loading = settled !== request; + + useEffect(() => { + let active = true; + host + .activity(1000) + .then( + (loaded) => { + if (active) { + setActivity(loaded); + setError(null); + } + }, + (reason: unknown) => { + if (active) { + setError(toHostError(reason).message); + } + }, + ) + .finally(() => { + if (active) { + setSettled(request); + } + }); + return () => { + active = false; + }; + }, [request]); + + const rows = useMemo(() => (activity ? activityRows(activity) : []), [activity]); + const shown = useMemo(() => filterActivity(rows, filter), [rows, filter]); + const filtered = filter.actor !== 'all' || filter.outcome !== 'all'; + + const save = () => { + host.saveTextFile(exportName(new Date()), 'jsonl', activityJsonl(shown)).then( + (path) => { + if (path !== null) { + setNote({ text: `Saved ${path}`, failed: false }); + } + }, + (reason: unknown) => { + setNote({ text: toHostError(reason).message, failed: true }); + }, + ); + }; + + return ( +
+
+ + + + {filtered + ? `${shown.length.toLocaleString('en-US')} of ${rows.length.toLocaleString('en-US')}` + : `${rows.length.toLocaleString('en-US')} newest first`} + + {filtered && ( + + )} + + {note !== null && ( + + {note.text} + + )} + {loading && } + + + + { + setManual((n) => n + 1); + }} + > + + +
+ +
+ {/* Inside the scrolling area, so it lines up with the rows beside a scrollbar. */} +
+ Time + By + Mode + Statement + Duration + Rows + Outcome + +
+ {error ? ( +

{error}

+ ) : shown.length === 0 ? ( +

+ {!activity + ? 'Loading' + : rows.length === 0 + ? 'Nothing has been run yet.' + : 'Nothing matches the filters.'} +

+ ) : ( + shown.map((row) => ) + )} +
+
+ ); +} + +function Row({ row, onOpenInEditor }: { row: ActivityRow; onOpenInEditor: (sql: string) => void }) { + const sql = row.sql; + const agent = row.channel === 'agent'; + return ( +
+ {formatTime(row.time)} + + + {agent ? 'Agent' : 'You'} + + + + {row.mode} + +
+
+ {row.label} +
+ {row.detail !== '' && ( +
+ {row.detail} +
+ )} + {row.error && ( +
+ {row.error} +
+ )} +
+ + {row.durationMs === null ? '' : formatElapsed(row.durationMs)} + + + {row.rowCount === null ? '' : row.rowCount.toLocaleString('en-US')} + + + {row.outcome} + + + {sql !== null && ( + { + onOpenInEditor(sql); + }} + > + + + )} + +
+ ); +} diff --git a/src/panes/chat/AssistantText.tsx b/src/panes/chat/AssistantText.tsx new file mode 100644 index 0000000..5dbab03 --- /dev/null +++ b/src/panes/chat/AssistantText.tsx @@ -0,0 +1,63 @@ +import { looksLikeSql, splitFences, type ToolItem } from '../../lib/chat'; +import { IconButton } from '../../ui/IconButton'; +import { OpenInEditor } from '../../ui/icons'; +import { ChartBlock } from './ChartBlock'; +import { Markdown } from './Markdown'; + +interface AssistantTextProps { + text: string; + onOpenInEditor: (sql: string) => void; + /** + * Given for a model's reply: the result sets a chart block can be drawn + * from, and where a result opens in the grid. Without it a chart block is + * shown as code, which is right for text that is not a reply. + */ + charts?: { + tables: ToolItem[]; + onShowTable: (item: ToolItem) => void; + }; +} + +/** + * Markdown text, with fenced code shown as code, SQL offered to the editor + * and chart blocks drawn. Used for a model's reply and for a query library + * document. + */ +export function AssistantText({ text, onOpenInEditor, charts }: AssistantTextProps) { + return ( +
+ {splitFences(text).map((segment, index) => + segment.kind === 'text' ? ( + + ) : charts && segment.language === 'chart' ? ( + + ) : ( +
+
+              {segment.code}
+            
+ {looksLikeSql(segment) && ( +
+ { + onOpenInEditor(segment.code); + }} + > + + +
+ )} +
+ ), + )} +
+ ); +} diff --git a/src/panes/chat/ChartBlock.tsx b/src/panes/chat/ChartBlock.tsx new file mode 100644 index 0000000..9837ae2 --- /dev/null +++ b/src/panes/chat/ChartBlock.tsx @@ -0,0 +1,134 @@ +import { memo, useMemo } from 'react'; +import type { ToolItem } from '../../lib/chat'; +import { + buildChart, + chartTitle, + parseChartSpec, + resolveChartData, + tableView, + type ChartData, + type ChartModel, + type ChartSpec, +} from '../../lib/chart'; +import { Spinner } from '../../ui/icons'; +import { ResultCard } from './ResultCard'; + +interface ChartBlockProps { + /** The text of the block. */ + source: string; + /** The block is still being written. */ + open: boolean; + /** The result sets it can be drawn from, oldest first. */ + tables: ToolItem[]; + onOpenInEditor: (sql: string) => void; + onShowTable: (item: ToolItem) => void; +} + +type Drawn = + | { + ok: true; + spec: ChartSpec; + data: ChartData; + /** The call the rows came from. Null when the block carried them. */ + item: ToolItem | null; + /** Null for a block that asks for a table. */ + model: ChartModel | null; + } + | { ok: false; error: string }; + +const EMPTY: ChartData = { columns: [], rows: [] }; + +/** Reads a block, finds its rows and works out what to draw. */ +function draw(source: string, tables: ToolItem[]): Drawn { + const parsed = parseChartSpec(source); + if (!parsed.ok) { + return parsed; + } + const spec = parsed.value; + const resolved = resolveChartData( + spec, + tables.map((item) => item.table ?? EMPTY), + ); + if (!resolved.ok) { + return resolved; + } + const { data, from } = resolved.value; + const item = from === null ? null : (tables[from] ?? null); + if (spec.type === 'table') { + return { ok: true, spec, data: tableView(spec, data), item, model: null }; + } + const built = buildChart(spec, data); + return built.ok ? { ok: true, spec, data, item, model: built.value } : built; +} + +/** + * A chart block from a reply, drawn. The block names columns. The rows + * come from a result set in the conversation, or from the block. A block + * that cannot be drawn is shown as the text it is, with the reason. + */ +function ChartBlockView({ source, open, tables, onOpenInEditor, onShowTable }: ChartBlockProps) { + const drawn = useMemo(() => (open ? null : draw(source, tables)), [open, source, tables]); + + if (drawn === null) { + return ( +
+ Drawing the chart +
+ ); + } + + if (!drawn.ok) { + return ( +
+
This chart could not be drawn. {drawn.error}
+
+          {source}
+        
+
+ ); + } + + const { spec, item, model } = drawn; + return ( +
+ { + onShowTable(item); + } + : undefined + } + /> +
+ ); +} + +const sameItems = (a: ToolItem[], b: ToolItem[]) => + a.length === b.length && a.every((item, index) => item === b[index]); + +/** + * A reply arrives in many pieces, and the conversation is laid out again + * for each. A chart is drawn again only when its own block or the result + * sets behind it have changed, not for every piece of text around it. + */ +export const ChartBlock = memo( + ChartBlockView, + (before, after) => + before.source === after.source && + before.open === after.open && + before.onOpenInEditor === after.onOpenInEditor && + before.onShowTable === after.onShowTable && + sameItems(before.tables, after.tables), +); diff --git a/src/panes/chat/ChatPane.tsx b/src/panes/chat/ChatPane.tsx new file mode 100644 index 0000000..0a187ca --- /dev/null +++ b/src/panes/chat/ChatPane.tsx @@ -0,0 +1,421 @@ +import { useEffect, useMemo, useRef, useState, type Ref } from 'react'; +import type { AgentConfig, SafetyMode } from '../../host/types'; +import { + SAFETY_MODES, + chatProgress, + chatTitle, + modeDescription, + pendingApprovals, + type ChatItem, + type ChatState, + type ToolItem, +} from '../../lib/chat'; +import { conversationBlocks, type Block } from '../../lib/conversation'; +import { IconButton } from '../../ui/IconButton'; +import { ArrowUp, Bot, ErrorMark, NewChat, Shield, Spinner, Stop, Warning } from '../../ui/icons'; +import { AssistantText } from './AssistantText'; +import { ResultCard } from './ResultCard'; +import { SessionChips } from './SessionChips'; +import { Steps, UsageText } from './Steps'; + +const BACKEND_LABEL: Record = { + gemini: 'Gemini', + anthropic: 'Anthropic', + openai_compatible: 'OpenAI-compatible', + github_copilot: 'GitHub Copilot', +}; + +interface ChatPaneProps { + /** Null until the configuration has been read. */ + config: AgentConfig | null; + chat: ChatState; + engineRunning: boolean; + /** Returns false when the message was not sent, so what was typed is kept. */ + onSend: (text: string) => boolean; + onStop: () => void; + onReset: () => void; + onAnswer: (approvalId: string, decision: 'accept' | 'decline') => void; + onSafetyMode: (mode: SafetyMode) => void; + onOpenInEditor: (sql: string) => void; + onShowTable: (item: ToolItem) => void; + onOpenModelSettings: () => void; + /** Things to ask, shown under an empty conversation. */ + suggestions: string[]; +} + +/** The conversation with the assistant. This is the app's main view. */ +export function ChatPane({ + config, + chat, + engineRunning, + onSend, + onStop, + onReset, + onAnswer, + onSafetyMode, + onOpenInEditor, + onShowTable, + onOpenModelSettings, + suggestions, +}: ChatPaneProps) { + const [draft, setDraft] = useState(''); + const end = useRef(null); + const input = useRef(null); + const waiting = pendingApprovals(chat).length > 0; + const empty = chat.items.length === 0; + const progress = chatProgress(chat); + const blocks = useMemo(() => conversationBlocks(chat), [chat]); + const backend = useMemo(() => backendOf(config), [config]); + + // Keep the newest text in view as the turn progresses. + useEffect(() => { + end.current?.scrollIntoView({ block: 'end' }); + }, [progress, waiting]); + + const send = () => { + if (chat.busy || !engineRunning || draft.trim() === '') { + return; + } + if (onSend(draft)) { + setDraft(''); + } + }; + + const composer = ( + + ); + + if (empty) { + return ( +
+
+

What do you want to query?

+

+ Ask about your cloud and SaaS providers in plain language. The assistant works through + the engine and shows every statement it runs as SQL. +

+ {composer} +
+ {suggestions.map((suggestion) => ( + + ))} +
+
+
+ ); + } + + return ( +
+
+ + {chatTitle(chat, 80)} + + + + +
+ +
+
+ {blocks.map((block) => ( + + ))} + {/* The steps say what is running. Before the first step there is only this. */} + {chat.busy && !blocks.some((block) => block.kind === 'steps' && block.active) && ( +
+ Working +
+ )} +
+
+
+ +
+
{composer}
+
+
+ ); +} + +/** The backend and model the configuration names. */ +function backendOf(config: AgentConfig | null): { + name: string; + model: string; + delegated: boolean; +} { + const inference = config?.inference ?? null; + const option = config?.backends.find((b) => b.kind === inference?.kind); + return { + name: inference ? (BACKEND_LABEL[inference.kind] ?? inference.kind) : '', + model: inference?.model || option?.defaultModel || '', + delegated: option?.delegated ?? false, + }; +} + +interface ComposerProps { + ref: Ref; + config: AgentConfig | null; + draft: string; + busy: boolean; + /** An approval prompt is open. */ + waiting: boolean; + engineRunning: boolean; + onDraft: (text: string) => void; + onSend: () => void; + onStop: () => void; + onSafetyMode: (mode: SafetyMode) => void; + onOpenModelSettings: () => void; +} + +/** Where the operator types, with the model and the safety mode under it. */ +function Composer({ + ref, + config, + draft, + busy, + waiting, + engineRunning, + onDraft, + onSend, + onStop, + onSafetyMode, + onOpenModelSettings, +}: ComposerProps) { + const inference = config?.inference ?? null; + const option = config?.backends.find((b) => b.kind === inference?.kind); + const delegated = option?.delegated ?? false; + const model = inference?.model || option?.defaultModel || ''; + const mode = config?.safetyMode ?? 'safe'; + const backend = inference + ? [BACKEND_LABEL[inference.kind] ?? inference.kind, model].filter(Boolean).join(', ') + : 'Set up a model'; + + return ( +
+ {waiting && ( +
+ Waiting for your decision above. +
+ )} +
+