feat: scaffold the Tauri shell, React UI and CI

Completes the Phase 0 scaffold. The app builds, links and renders; no
screens yet.

Frontend (ARCHITECTURE section 9, UI-SPEC section 2):
- React 19 + Vite 8 + Tailwind 4 with the UI-SPEC dark terminal-tech
  tokens, plus a contrast test asserting WCAG AA over every
  text/surface pair, which UI-SPEC section 8 requires be verified.
- EN and VI catalogs with a test that vi has every en key and no
  orphans, standing in for the CI parity script I18N section 1 asks for.
- A local eslint rule enforcing the no-hardcoded-JSX-strings policy.
  eslint-plugin-react was the obvious choice but caps at ESLint 9, which
  drags in six high-severity advisories that would fail npm audit in CI;
  a local rule also implements the documented allowlist (product name,
  package names, versions, catalog codes, glyphs) precisely, which
  react/jsx-no-literals cannot express. Verified it fires on real copy
  and stays quiet on all five allowed shapes.
- no-restricted-imports keeps invoke() out of components, so the
  "no component calls invoke directly" rule is enforced, not just stated.

Tauri (ARCHITECTURE section 7): commands and events only, identifier
com.skullmute.pipdock, NSIS and MSI targets, minimal capability set,
placeholder icon pending the Phase 3 branding pass.

CI (docs/RELEASE-CI.md section 1 as corrected):
- ci-rust.yml and release.yml are project-local, on Windows runners,
  because no reusable Rust or Tauri workflow exists in the ops repo.
  Windows matters here: env discovery reads the PEP 514 registry and the
  py launcher, so a Linux run would skip the code most likely to break.
- ci-node.yml calls the ops web-react reusable and adds the npm audit
  job that reusable lacks.
- codeql.yml is JS/TS only; CodeQL has no Rust analyzer.
- Discord notifiers replace the six-platform notify.yml that never
  existed. Every caller carries an explicit permissions block.
- Action versions checked against the registry rather than assumed:
  checkout v7, cache v6, gh-release v3, setup-node v6.

Two toolchain holds, both forced and both recorded:
- TypeScript 6.0.3, not 7: typescript-eslint peers on <6.1.0.
- ESLint 10 with eslint-plugin-react dropped, as above.

Verified: cargo fmt/clippy -D warnings/28 tests green, tsc clean,
18 vitest tests green, eslint clean, npm audit reports 0
vulnerabilities, vite build and both binaries link.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-27 17:44:39 +07:00
1 parent c4fe1c34e6
commit 8f6b7ed24b
57 files changed
+9397 -36

No files matched your search

+11
View File
@@ -0,0 +1,11 @@
# RELEASE-CI.md §5: blank issues disabled so every report carries the fields the triage flow and
# the in-app "Report bug" deep link depend on (ERROR-CATALOG §4).
blank_issues_enabled: false
contact_links:
- name: Question or idea
url: https://github.com/poli0981/pipdock/discussions
about: Ask about usage, propose a feature, or share a workflow.
- name: Security vulnerability
url: https://github.com/poli0981/pipdock/security/advisories/new
about: Report privately via GitHub Security Advisories. Please do not open a public issue.
+52
View File
@@ -0,0 +1,52 @@
# Dependency updates — docs/RELEASE-CI.md §2.
#
# Dependabot, not Renovate: there is no Renovate configuration anywhere in the poli0981/.github
# ops repo, and that repo ships a dependabot-summary.yml, which makes Dependabot the portfolio
# standard.
#
# Grouping intent carried over from the original spec: weekly grouped minor/patch PRs per
# ecosystem, and Code Health pins kept in their own group so they stay reviewable in isolation.
# Security advisories bypass grouping and schedule automatically — that is Dependabot's default
# for security updates and cannot be configured away here.
version: 2
updates:
- package-ecosystem: cargo
directory: /
schedule:
interval: weekly
day: monday
open-pull-requests-limit: 5
groups:
cargo-minor-patch:
update-types: [minor, patch]
labels: [dependencies, rust]
- package-ecosystem: npm
directory: /
schedule:
interval: weekly
day: monday
open-pull-requests-limit: 5
groups:
npm-minor-patch:
update-types: [minor, patch]
labels: [dependencies, frontend]
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
day: monday
labels: [dependencies, ci]
# Code Health tool pins (deptry / vulture / ruff), shipped with the app and resolved at release
# time — CODE-HEALTH-SPEC §2. Kept as its own ecosystem so a bump here is never bundled with
# application dependencies.
- package-ecosystem: pip
directory: /tools
schedule:
interval: weekly
day: monday
labels: [dependencies, code-health]
+28
View File
@@ -0,0 +1,28 @@
# Caller into the ops repo's Discord announcer.
#
# docs/RELEASE-CI.md §1 originally described a `notify.yml` cross-posting to six platforms; the
# ops repo has no such workflow. Announcements are Discord-only, via
# poli0981/.github/.github/scripts/discord_notify.py.
name: Announce Release
on:
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: Tag to announce (for re-runs)
required: true
type: string
permissions:
contents: read
actions: read
jobs:
announce:
uses: poli0981/.github/.github/workflows/announce-release.yml@main
with:
tag_override: ${{ inputs.tag || '' }}
secrets: inherit
+53
View File
@@ -0,0 +1,53 @@
# Caller into the ops repo's React reusable, plus one local job.
#
# The reusable runs Node 24, `npm ci`, then lint / typecheck / test when the matching npm script
# exists, then the build. It has no `npm audit` step, so that gate lives here — see
# docs/RELEASE-CI.md §1.
#
# It also has no working-directory input, which is why package.json sits at the repo root with
# Vite configured `root: './ui'` (ARCHITECTURE §2).
name: CI / Node
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: ci-node-${{ github.ref }}
cancel-in-progress: true
jobs:
web:
name: lint · typecheck · test · build
uses: poli0981/.github/.github/workflows/reusable-web-react.yml@main
with:
node-version: '24'
package-manager: npm
build-command: npm run build
dist-dir: dist
deploy-pages: false
audit:
name: npm audit
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: '24'
cache: npm
- name: Install
run: npm ci
- name: Audit
run: npm audit --audit-level=high
+73
View File
@@ -0,0 +1,73 @@
# Project-local: the ops repo (poli0981/.github) has no reusable Rust workflow, and only its
# desktop-csharp reusable runs on Windows. See docs/RELEASE-CI.md §1.
#
# Windows runner because the environment-discovery module reads the PEP 514 registry and the `py`
# launcher — a Linux run would skip exactly the code most likely to break.
name: CI / Rust
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: ci-rust-${{ github.ref }}
cancel-in-progress: true
env:
CARGO_TERM_COLOR: always
RUSTFLAGS: -D warnings
jobs:
check:
name: fmt · clippy · test
runs-on: windows-latest
timeout-minutes: 45
steps:
- name: Checkout
uses: actions/checkout@v7
# rust-toolchain.toml pins the exact version, so no toolchain action is needed — rustup
# honours it on first invocation and installs rustfmt and clippy with it.
- name: Show toolchain
run: |
rustup show
cargo --version
- name: Cache cargo
uses: actions/cache@v6
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }}
restore-keys: ${{ runner.os }}-cargo-
- name: Format
run: cargo fmt --all -- --check
- name: Clippy
run: cargo clippy --workspace --all-targets --locked -- -D warnings
- name: Test
run: cargo test --workspace --locked
audit:
name: cargo audit
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout
uses: actions/checkout@v7
# RustSec advisories against the committed Cargo.lock. Split from the Windows job because
# it needs no toolchain pin and no target build — it is a lockfile scan.
- name: Audit
uses: rustsec/audit-check@v2
with:
token: ${{ secrets.GITHUB_TOKEN }}
+30
View File
@@ -0,0 +1,30 @@
# Caller into the ops repo's CodeQL reusable.
#
# JavaScript/TypeScript only: CodeQL has no Rust analyzer, and the reusable's supported set is
# csharp, python, javascript-typescript, ruby, c-cpp, java-kotlin, go and swift. Rust's static
# analysis is clippy `-D warnings` plus `cargo audit`, both blocking in ci-rust.yml.
# See docs/RELEASE-CI.md §1 and docs/SECURITY.md §7.
#
# The reusable notes that repo Settings → Advanced Security → CodeQL "Default setup" must be
# DISABLED, or this advanced-setup workflow is rejected at upload time.
name: CodeQL
on:
pull_request:
push:
branches: [main]
schedule:
# Weekly, offset off the hour to avoid the top-of-hour scheduling pileup.
- cron: '37 4 * * 1'
permissions:
actions: read
contents: read
security-events: write
jobs:
analyze:
uses: poli0981/.github/.github/workflows/reusable-codeql.yml@main
with:
languages: '["javascript-typescript"]'
+20
View File
@@ -0,0 +1,20 @@
# Caller into the ops repo's Discord CI-failure notifier.
#
# The reusable skips workflows that have their own dedicated notifier (release, CodeQL,
# Dependabot), so this does not double-report.
name: Notify CI Failure
on:
workflow_run:
workflows: ['*']
types: [completed]
permissions:
contents: read
actions: read
jobs:
notify:
uses: poli0981/.github/.github/workflows/notify-ci-failure.yml@main
secrets: inherit
+97
View File
@@ -0,0 +1,97 @@
# Project-local: the ops repo has no reusable Tauri/build workflow (docs/RELEASE-CI.md §1).
#
# Produces the NSIS .exe and .msi, signs the updater artifacts, publishes SHA256SUMS.txt and
# leaves a DRAFT release for owner review. Publishing is manual on purpose — RELEASE-CI.md §3.4 —
# and announce-release.yml fires on `release: published`.
name: Release
on:
push:
tags: ['v*']
workflow_dispatch:
inputs:
tag:
description: Tag to build (for re-runs)
required: true
type: string
permissions:
contents: write # release assets
concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false
env:
CARGO_TERM_COLOR: always
jobs:
build:
name: Build · sign · draft
runs-on: windows-latest
timeout-minutes: 90
steps:
- name: Checkout
uses: actions/checkout@v7
with:
ref: ${{ inputs.tag || github.ref }}
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: '24'
cache: npm
- name: Cache cargo
uses: actions/cache@v6
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }}
restore-keys: ${{ runner.os }}-cargo-release-
- name: Install frontend dependencies
run: npm ci
- name: Build frontend
run: npm run build
- name: Build, bundle and sign
env:
# Private key lives only in Actions secrets (docs/SECURITY.md §5); the matching public
# key is baked into tauri.conf.json so the app verifies updates before applying them.
TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
run: npx tauri build --locked --bundles nsis,msi,updater
- name: Collect artifacts
shell: pwsh
run: |
$out = "release-artifacts"
New-Item -ItemType Directory -Force $out | Out-Null
Get-ChildItem -Recurse target\release\bundle `
-Include *.exe, *.msi, *.zip, *.sig, latest.json |
ForEach-Object { Copy-Item $_.FullName $out }
Get-ChildItem $out
- name: Publish checksums
shell: pwsh
run: |
# SmartScreen warns on first run because the binaries are not EV-code-signed, so the
# README tells users to verify these instead (docs/SECURITY.md §5).
Get-ChildItem release-artifacts -File |
Where-Object { $_.Name -ne 'SHA256SUMS.txt' } |
ForEach-Object { "$((Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLower()) $($_.Name)" } |
Set-Content release-artifacts\SHA256SUMS.txt -Encoding ascii
Get-Content release-artifacts\SHA256SUMS.txt
- name: Draft GitHub release
uses: softprops/action-gh-release@v3
with:
tag_name: ${{ inputs.tag || github.ref_name }}
draft: true # owner reviews, then publishes; publishing triggers the announcement
generate_release_notes: true
files: release-artifacts/*
Generated
+3433 -31
View File
File diff suppressed because it is too large. Load diff
+1 -1
View File
@@ -1,6 +1,6 @@
[workspace] [workspace]
resolver = "3" resolver = "3"
members = ["crates/pipdock-core", "crates/pipdock-cli"] members = ["crates/pipdock-core", "crates/pipdock-cli", "src-tauri"]
[workspace.package] [workspace.package]
version = "0.1.0" version = "0.1.0"
+8 -4
View File
@@ -56,8 +56,12 @@ Two active lines at most: latest release gets features; previous minor gets secu
## 5. Repo scaffolding checklist (day one) ## 5. Repo scaffolding checklist (day one)
- [ ] GPL-3.0 `LICENSE` at root; `legal/` committed **publicly** (the in-app legal gate links to these GitHub URLs — CommandForge lesson: don't leave them gitignored). - [x] GPL-3.0 `LICENSE` at root; `legal/` committed **publicly** (the in-app legal gate links to these GitHub URLs — CommandForge lesson: don't leave them gitignored).
- [ ] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues. - [x] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues.
- [ ] Branch protection, Dependabot, CodeQL (JS/TS), secrets via `gh secret set`. - [x] `.github/dependabot.yml` covering cargo, npm, github-actions and the Code Health pins.
- [ ] `rust-toolchain.toml`, `.nvmrc` (24), `Cargo.lock`/`package-lock.json` committed. - [x] `rust-toolchain.toml`, `.nvmrc` (24), `Cargo.lock`/`package-lock.json` committed.
- [ ] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (the reusable is advanced-setup and is rejected at upload time otherwise); enable Discussions for the issue-template contact links.
- [ ] **Secrets via `gh secret set`:** `TAURI_SIGNING_PRIVATE_KEY`, `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`, and the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`).
- [ ] **Generate the updater keypair** (`npx tauri signer generate`) and replace the `plugins.updater.pubkey` placeholder in `src-tauri/tauri.conf.json` with the public half. Until then the updater cannot verify a release.
- [ ] Replace the placeholder app icon (`src-tauri/icons/`) in the ROADMAP Phase 3 branding pass.
- [ ] README badges: CI, CodeQL, release, license. - [ ] README badges: CI, CodeQL, release, license.
+106
View File
@@ -0,0 +1,106 @@
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
/**
* `docs/I18N.md` §1 — the no-hardcoded-strings rule.
*
* Every user-visible string must come from an i18next catalog, so untranslated copy can never
* ship. The documented allowlist is `PipDock`, package names, versions and catalog codes, which is
* pattern-shaped rather than a fixed word list — so this is a local rule instead of
* `react/jsx-no-literals` (which also caps out at ESLint 9 and pulls a vulnerable minimatch).
*/
const noJsxLiterals = {
meta: {
type: 'problem',
docs: { description: 'JSX text must come from an i18next catalog (docs/I18N.md §1)' },
schema: [],
messages: {
literal:
'Hardcoded JSX text {{text}} — use t() with a key from ui/src/locales (docs/I18N.md §1).',
},
},
create(context) {
// Allowed without translation: the product name, PEP 503 package names, PEP 440 versions,
// catalog codes, and pure punctuation/symbols (the terminal glyphs in UI-SPEC §7).
const allowed = [
/^PipDock$/,
/^[a-z0-9][a-z0-9._-]*$/, // package name
/^v?\d+(\.\d+)*([a-z].*)?$/i, // version
/^PD-[A-Z]{3}-\d{3}$/, // catalog code
/^[^\p{L}\p{N}]+$/u, // punctuation and glyphs only
]
const check = (node, raw) => {
const text = raw.trim()
if (!text) return
if (allowed.some((re) => re.test(text))) return
context.report({ node, messageId: 'literal', data: { text: JSON.stringify(text) } })
}
return {
JSXText: (node) => check(node, node.value),
JSXExpressionContainer(node) {
if (node.expression.type === 'Literal' && typeof node.expression.value === 'string') {
check(node, node.expression.value)
}
},
}
},
}
export default tseslint.config(
{ ignores: ['dist/**', 'target/**', 'src-tauri/target/**', 'node_modules/**'] },
js.configs.recommended,
...tseslint.configs.recommendedTypeChecked,
{
files: ['ui/src/**/*.{ts,tsx}'],
languageOptions: {
parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
},
plugins: {
'react-hooks': reactHooks,
'react-refresh': reactRefresh,
pipdock: { rules: { 'no-jsx-literals': noJsxLiterals } },
},
rules: {
...reactHooks.configs.recommended.rules,
'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
'pipdock/no-jsx-literals': 'error',
// ARCHITECTURE §9: no component calls `invoke` directly — everything goes through the typed
// wrappers in ui/src/ipc, which are the only place Rust types cross into TS.
'no-restricted-imports': [
'error',
{
paths: [
{
name: '@tauri-apps/api/core',
importNames: ['invoke'],
message: 'Import a typed wrapper from @/ipc instead (ARCHITECTURE §9).',
},
],
},
],
},
},
// The IPC layer is the one place allowed to call invoke().
{
files: ['ui/src/ipc/**/*.ts'],
rules: { 'no-restricted-imports': 'off' },
},
// Tests assert on real copy, so literals are expected there.
{
files: ['ui/src/**/*.test.{ts,tsx}', 'ui/src/test/**/*.{ts,tsx}'],
rules: { 'pipdock/no-jsx-literals': 'off' },
},
// Config files are plain Node modules, outside the type-aware program.
{
files: ['*.js', '*.ts'],
...tseslint.configs.disableTypeChecked,
},
)
+4584
View File
File diff suppressed because it is too large. Load diff
+54
View File
@@ -0,0 +1,54 @@
{
"name": "pipdock",
"version": "0.1.0",
"private": true,
"description": "A friendly dock for your Python environments — bulk inspect, install, update and clean up Python packages.",
"license": "GPL-3.0-only",
"type": "module",
"repository": {
"type": "git",
"url": "git+https://github.com/poli0981/pipdock.git"
},
"bugs": {
"url": "https://github.com/poli0981/pipdock/issues"
},
"homepage": "https://github.com/poli0981/pipdock#readme",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview",
"lint": "eslint .",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"test:watch": "vitest",
"tauri": "tauri"
},
"dependencies": {
"@tauri-apps/api": "^2.11.1",
"i18next": "^26.3.6",
"react": "^19.2.8",
"react-dom": "^19.2.8",
"react-i18next": "^17.0.11",
"zustand": "^5.0.14"
},
"devDependencies": {
"@eslint/js": "^10.0.1",
"@tailwindcss/vite": "^4.3.3",
"@tauri-apps/cli": "^2.11.4",
"@testing-library/jest-dom": "^7.0.0",
"@testing-library/react": "^16.3.2",
"@types/node": "^26.1.1",
"@types/react": "^19.2.17",
"@types/react-dom": "^19.2.3",
"@vitejs/plugin-react": "^6.0.4",
"eslint": "^10.8.0",
"eslint-plugin-react-hooks": "^7.1.1",
"eslint-plugin-react-refresh": "^0.5.3",
"jsdom": "^30.0.0",
"tailwindcss": "^4.3.3",
"typescript": "^6.0.3",
"typescript-eslint": "^8.65.0",
"vite": "^8.1.5",
"vitest": "^4.1.10"
}
}
+30
View File
@@ -0,0 +1,30 @@
[package]
name = "pipdock-app"
description = "PipDock — Tauri shell. Commands and events only; all logic lives in pipdock-core."
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
repository.workspace = true
authors.workspace = true
[lib]
name = "pipdock_app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]
[lints]
workspace = true
[build-dependencies]
tauri-build = { version = "2", features = [] }
[dependencies]
pipdock-core = { path = "../crates/pipdock-core" }
tauri = { version = "2", features = [] }
tauri-plugin-updater = "2"
tauri-plugin-dialog = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["rt-multi-thread"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+3
View File
@@ -0,0 +1,3 @@
fn main() {
tauri_build::build();
}
+11
View File
@@ -0,0 +1,11 @@
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"description": "Minimal capability set for the Phase 0 shell. Permissions are added per feature, never broadened preemptively (docs/SECURITY.md §2).",
"windows": ["main"],
"permissions": [
"core:default",
"dialog:allow-open",
"updater:default"
]
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 1.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 663 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 637 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 870 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 942 B

Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.3 KiB

+27
View File
@@ -0,0 +1,27 @@
//! Tauri commands.
//!
//! ARCHITECTURE §1.1: each command is a **thin** wrapper over a `pipdock_core` function. If a
//! wrapper starts making decisions, that logic belongs in the core instead, so the CLI inherits
//! it too (G5: GUI and CLI never diverge).
//!
//! The full surface is fixed by ARCHITECTURE §7 (`env_scan`, `pkg_list`, `plan_resolve`,
//! `plan_execute`, …) and mirrored in `ui/src/ipc`. Those wrappers land in M2 with the screens;
//! only the bridge smoke test exists in Phase 0.
/// What the shell can report before any core wiring exists.
#[derive(serde::Serialize)]
pub struct AppInfo {
/// PipDock's own version, from Cargo.
pub version: &'static str,
/// The milestone this build belongs to.
pub phase: &'static str,
}
/// Smoke-test command: proves the IPC bridge is wired before any real command exists.
#[tauri::command]
pub fn app_info() -> AppInfo {
AppInfo {
version: env!("CARGO_PKG_VERSION"),
phase: "phase-0",
}
}
+26
View File
@@ -0,0 +1,26 @@
//! The Tauri shell.
//!
//! ARCHITECTURE §1.1: this crate contains **commands and events only**. Every command is a thin
//! wrapper over a `pipdock_core` function — if a code path here starts making decisions, it
//! belongs in the core so the CLI gets the same behaviour (G5: GUI and CLI never diverge).
pub mod commands;
/// Run the application.
///
/// # Panics
/// Panics if Tauri cannot build the app context. That means a malformed `tauri.conf.json`, which
/// is a build-time mistake rather than a runtime condition, so there is nothing to recover to.
#[cfg_attr(mobile, tauri::mobile_entry_point)]
#[allow(
clippy::expect_used,
reason = "no usable app state exists if the context fails to build"
)]
pub fn run() {
tauri::Builder::default()
.plugin(tauri_plugin_dialog::init())
.plugin(tauri_plugin_updater::Builder::new().build())
.invoke_handler(tauri::generate_handler![commands::app_info])
.run(tauri::generate_context!())
.expect("error while running PipDock");
}
+6
View File
@@ -0,0 +1,6 @@
// Release builds must not open a console window behind the GUI.
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
fn main() {
pipdock_app_lib::run();
}
+48
View File
@@ -0,0 +1,48 @@
{
"$schema": "https://schema.tauri.app/config/2",
"productName": "PipDock",
"version": "0.1.0",
"identifier": "com.skullmute.pipdock",
"build": {
"beforeDevCommand": "npm run dev",
"beforeBuildCommand": "npm run build",
"devUrl": "http://localhost:1420",
"frontendDist": "../dist"
},
"app": {
"windows": [
{
"title": "PipDock",
"width": 1180,
"height": 760,
"minWidth": 900,
"minHeight": 560,
"resizable": true,
"theme": "Dark"
}
],
"security": {
"csp": "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self'; connect-src 'self' ipc: http://ipc.localhost"
}
},
"bundle": {
"active": true,
"targets": ["nsis", "msi"],
"icon": ["icons/icon.ico"],
"copyright": "Copyright (C) 2026 Kokone (poli0981). Licensed under GPL-3.0-only.",
"category": "DeveloperTool",
"shortDescription": "A friendly dock for your Python environments.",
"longDescription": "Inspect, install, update and clean up Python packages in bulk, with a preview of every change, three-way conflict handling and one-click rollback.",
"windows": {
"allowDowngrades": false
}
},
"plugins": {
"updater": {
"endpoints": [
"https://github.com/poli0981/pipdock/releases/latest/download/latest.json"
],
"pubkey": "REPLACE_AT_FIRST_RELEASE_WITH_TAURI_SIGNING_PUBLIC_KEY"
}
}
}
+20
View File
@@ -0,0 +1,20 @@
# Code Health tools — CODE-HEALTH-SPEC §2.
#
# These are installed into PipDock's own isolated environment at
# %LOCALAPPDATA%\PipDock\tools\.venv, NEVER into the user's environment. Exact `==` pins are
# resolved at PipDock release time; there are no floating versions at runtime, so a report is
# reproducible for a given PipDock build.
#
# Dependabot bumps these in their own group (see .github/dependabot.yml) so a tool upgrade is
# never bundled with application dependencies — a ruff minor can change findings across every
# user's report, and that deserves its own review.
#
# Versions verified against PyPI 2026-07-27.
deptry==0.25.1
vulture==2.16
ruff==0.16.0
# P1 (Security tab, PRD P1-1). Pinned now so spike SP-4 has something concrete to invoke while
# it settles the foreign-environment audit flags.
pip-audit==2.10.1
+34
View File
@@ -0,0 +1,34 @@
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2023", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"types": ["vite/client", "node", "vitest/globals", "@testing-library/jest-dom"],
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"exactOptionalPropertyTypes": true,
"verbatimModuleSyntax": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"skipLibCheck": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"forceConsistentCasingInFileNames": true,
// No baseUrl: it is deprecated in TypeScript 6 and removed in 7. Path mappings resolve
// relative to this file instead.
"paths": {
"@/*": ["./ui/src/*"]
}
},
"include": ["ui/src", "vite.config.ts", "eslint.config.js"]
}
+16
View File
@@ -0,0 +1,16 @@
<!doctype html>
<html lang="en" class="dark">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta
http-equiv="Content-Security-Policy"
content="default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self'; connect-src 'self' ipc: http://ipc.localhost"
/>
<title>PipDock</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
+34
View File
@@ -0,0 +1,34 @@
import { useTranslation } from 'react-i18next'
import { PdSidebar } from '@/components/PdSidebar'
import { PdStatusLine } from '@/components/PdStatusLine'
/**
* The app shell — UI-SPEC §3.
*
* Top bar, sidebar, content area and a pinned terminal-style status line. The console drawer
* slides up over the status line during execution; screens fill the content area in M2.
*/
export function App() {
const { t } = useTranslation()
return (
<div className="flex h-full flex-col bg-bg text-text">
<header className="flex items-center justify-between border-b border-border px-4 py-2">
<span className="font-mono text-accent">{t('app.name')}</span>
<span className="font-mono text-[13px] text-text-dim">{t('status.noEnvironment')}</span>
</header>
<div className="flex min-h-0 flex-1">
<PdSidebar />
<main className="min-w-0 flex-1 overflow-auto p-6">
<h1 className="text-accent">{t('phase0.heading')}</h1>
<p className="mt-2 max-w-prose text-text-dim">{t('phase0.body')}</p>
<p className="mt-4 font-mono text-[13px] text-accent-dim">{t('phase0.docs')}</p>
</main>
</div>
<PdStatusLine />
</div>
)
}
+25
View File
@@ -0,0 +1,25 @@
import { useTranslation } from 'react-i18next'
import { NAV_KEYS } from '@/components/nav'
/**
* The sidebar — UI-SPEC §3 and §8.
*
* Icon + label, collapsible to icons. `Ctrl+1..8` selects a tab; the keyboard map lands with the
* screens in M2, so the entries render but are inert here.
*/
export function PdSidebar() {
const { t } = useTranslation()
return (
<nav aria-label={t('nav.environments')} className="w-48 shrink-0 border-r border-border p-2">
<ul className="space-y-0.5">
{NAV_KEYS.map((key) => (
<li key={key}>
<span className="block rounded-[6px] px-3 py-1.5 text-text-dim">{t(`nav.${key}`)}</span>
</li>
))}
</ul>
</nav>
)
}
+27
View File
@@ -0,0 +1,27 @@
import { useTranslation } from 'react-i18next'
import { useSettingsStore } from '@/stores'
/**
* The status line — UI-SPEC §3.
*
* Always shows env · python · engine · state in monospace, plus the log-drawer toggle. The
* engine badge carries the live-activity pulse during execution (UI-SPEC §2).
*/
export function PdStatusLine() {
const { t } = useTranslation()
const engine = useSettingsStore((s) => s.engine)
return (
<footer className="flex items-center gap-3 border-t border-border bg-surface px-4 py-1.5 font-mono text-[13px] text-text-dim">
<span aria-hidden="true">{'▸'}</span>
<span>{t('status.noEnvironment')}</span>
<span aria-hidden="true">{'·'}</span>
{/* Engine ids are never translated (docs/I18N.md §2). */}
<span className="text-accent">{engine}</span>
<span aria-hidden="true">{'·'}</span>
<span>{t('status.idle')}</span>
<span className="ml-auto">{t('status.log')}</span>
</footer>
)
}
+18
View File
@@ -0,0 +1,18 @@
/**
* Sidebar tab order — UI-SPEC §3 and §8.
*
* The order is load-bearing: `Ctrl+1..8` maps to it positionally, so reordering these entries
* silently rebinds the user's shortcuts.
*/
export const NAV_KEYS = [
'environments',
'installed',
'updates',
'search',
'pins',
'health',
'security',
'settings',
] as const
export type NavKey = (typeof NAV_KEYS)[number]
+44
View File
@@ -0,0 +1,44 @@
import { describe, expect, it } from 'vitest'
import { FALLBACK_LOCALE, resolveLocale, resources, SUPPORTED_LOCALES } from './i18n'
/** Collect every leaf key path in a nested catalog, e.g. `nav.updates`. */
function keyPaths(obj: unknown, prefix = ''): string[] {
if (typeof obj !== 'object' || obj === null) return [prefix]
return Object.entries(obj).flatMap(([k, v]) => keyPaths(v, prefix ? `${prefix}.${k}` : k))
}
describe('i18n catalogs', () => {
it('vi has every key en has', () => {
// docs/I18N.md §1: a CI script fails the build if vi is missing keys. This is that check.
const en = new Set(keyPaths(resources.en.common))
const vi = new Set(keyPaths(resources.vi.common))
const missing = [...en].filter((k) => !vi.has(k))
expect(missing, `vi is missing: ${missing.join(', ')}`).toEqual([])
})
it('vi has no keys en lacks', () => {
const en = new Set(keyPaths(resources.en.common))
const extra = [...new Set(keyPaths(resources.vi.common))].filter((k) => !en.has(k))
expect(extra, `vi has orphans: ${extra.join(', ')}`).toEqual([])
})
it('the product name is never translated', () => {
// docs/I18N.md §2: package names, versions, engine output and codes are never translated,
// and the eslint allowlist treats "PipDock" as a literal for the same reason.
expect(resources.vi.common.app.name).toBe(resources.en.common.app.name)
})
it.each(SUPPORTED_LOCALES)('%s catalog is non-empty', (locale) => {
expect(keyPaths(resources[locale].common).length).toBeGreaterThan(0)
})
it('resolves OS language tags to a supported locale', () => {
expect(resolveLocale('vi-VN')).toBe('vi')
expect(resolveLocale('vi')).toBe('vi')
expect(resolveLocale('en-GB')).toBe('en')
// Anything else falls back to English rather than showing keys (docs/I18N.md §2).
expect(resolveLocale('ja-JP')).toBe(FALLBACK_LOCALE)
expect(resolveLocale(undefined)).toBe(FALLBACK_LOCALE)
expect(resolveLocale('')).toBe(FALLBACK_LOCALE)
})
})
+50
View File
@@ -0,0 +1,50 @@
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import enCommon from './locales/en/common.json'
import viCommon from './locales/vi/common.json'
/**
* i18next setup — `docs/I18N.md`.
*
* §1: `en` is the source of truth; missing `vi` keys fall back to English at runtime with a
* console warning, **never** raw key names in the UI. A CI script fails the build when `vi` is
* short of keys, so the fallback is a safety net rather than a strategy.
*
* §2: default locale is the OS UI language when it is Vietnamese, else English; switchable in
* Settings and applied live.
*/
export const SUPPORTED_LOCALES = ['en', 'vi'] as const
export type Locale = (typeof SUPPORTED_LOCALES)[number]
export const FALLBACK_LOCALE: Locale = 'en'
/** Resolve a browser/OS language tag such as `vi-VN` to a supported locale. */
export function resolveLocale(languageTag: string | undefined): Locale {
const base = (languageTag ?? '').split('-')[0]?.toLowerCase()
return SUPPORTED_LOCALES.includes(base as Locale) ? (base as Locale) : FALLBACK_LOCALE
}
export const resources = {
en: { common: enCommon },
vi: { common: viCommon },
} as const
void i18n.use(initReactI18next).init({
resources,
lng: resolveLocale(typeof navigator === 'undefined' ? undefined : navigator.language),
fallbackLng: FALLBACK_LOCALE,
defaultNS: 'common',
interpolation: {
// React already escapes; double-escaping mangles Vietnamese diacritics in some browsers.
escapeValue: false,
},
// Surfaces the fallback in development instead of letting untranslated copy pass unnoticed.
saveMissing: false,
missingKeyHandler: (lngs, ns, key) => {
console.warn(`[i18n] missing key ${ns}:${key} for ${lngs.join(',')}`)
},
})
export default i18n
+59
View File
@@ -0,0 +1,59 @@
/**
* The typed IPC boundary — ARCHITECTURE §9.
*
* **No component calls `invoke` directly.** Everything crosses through this module, which is the
* one place `@tauri-apps/api/core` may be imported (enforced by `no-restricted-imports` in
* `eslint.config.js`).
*
* In M2 the request/response types here are generated by `specta`/`tauri-specta` from the Rust
* definitions so drift between core and UI becomes a compile error rather than a runtime surprise.
* Until that generation is wired up, this module only declares the command names — which are
* already fixed by ARCHITECTURE §7 — so the surface is reviewable now.
*/
/** Every Tauri command, per ARCHITECTURE §7. All are async and all return `Result<T, PdError>`. */
export const COMMANDS = [
'env_scan',
'env_add_manual',
'env_probe',
'pkg_list',
'pkg_outdated',
'index_search',
'pkg_metadata',
'plan_resolve',
'plan_execute',
'plan_cancel',
'uninstall_guard',
'uninstall_execute',
'pin_list',
'pin_add',
'pin_remove',
'snapshot_list',
'snapshot_diff',
'snapshot_rollback',
'health_run',
'health_fix',
'settings_get',
'settings_set',
'logs_tail',
'pip_upgrade',
'legal_consent_get',
'legal_consent_set',
] as const
export type Command = (typeof COMMANDS)[number]
/** Tauri event channels, per ARCHITECTURE §7. */
export const EVENTS = ['plan-progress', 'scan-progress', 'health-progress'] as const
export type EventName = (typeof EVENTS)[number]
/** The error shape every command rejects with; mirrors `pipdock_core::errors::PdError`. */
export interface PdError {
/** Catalog code, e.g. `PD-BLD-002`. Never localized (docs/I18N.md §1). */
code: string
/** Developer-facing detail. The user-facing one-liner is looked up from `code`. */
message: string
/** Engine stderr tail, at most 40 lines (docs/ERROR-CATALOG.md §3). */
stderrTail?: string
}
+40
View File
@@ -0,0 +1,40 @@
{
"app": {
"name": "PipDock",
"tagline": "A friendly dock for your Python environments."
},
"nav": {
"environments": "Environments",
"installed": "Installed",
"updates": "Updates",
"search": "Search",
"pins": "Pins",
"health": "Health",
"security": "Security",
"settings": "Settings"
},
"status": {
"idle": "idle",
"scanning": "scanning",
"resolving": "resolving",
"executing": "executing",
"log": "log",
"noEnvironment": "no environment selected"
},
"actions": {
"confirm": "Confirm",
"cancel": "Cancel",
"back": "Back",
"rescan": "Rescan",
"browse": "Browse…",
"selectAll": "Select all",
"details": "Details",
"copyLog": "Copy full log",
"reportBug": "Report bug"
},
"phase0": {
"heading": "Phase 0 — scaffold",
"body": "The shell, design tokens and locale catalogs are in place. Screens land in M2, after the Phase 0 spikes answer how each engine reports its dry-run plan.",
"docs": "See docs/ROADMAP.md"
}
}
+40
View File
@@ -0,0 +1,40 @@
{
"app": {
"name": "PipDock",
"tagline": "Bến đỗ thân thiện cho các môi trường Python của bạn."
},
"nav": {
"environments": "Môi trường",
"installed": "Đã cài",
"updates": "Cập nhật",
"search": "Tìm kiếm",
"pins": "Ghim",
"health": "Sức khỏe mã",
"security": "Bảo mật",
"settings": "Cài đặt"
},
"status": {
"idle": "rảnh",
"scanning": "đang quét",
"resolving": "đang phân giải",
"executing": "đang chạy",
"log": "nhật ký",
"noEnvironment": "chưa chọn môi trường"
},
"actions": {
"confirm": "Xác nhận",
"cancel": "Hủy",
"back": "Quay lại",
"rescan": "Quét lại",
"browse": "Duyệt…",
"selectAll": "Chọn tất cả",
"details": "Chi tiết",
"copyLog": "Sao chép toàn bộ nhật ký",
"reportBug": "Báo lỗi"
},
"phase0": {
"heading": "Giai đoạn 0 — dựng khung",
"body": "Khung ứng dụng, design token và các catalog ngôn ngữ đã sẵn sàng. Các màn hình sẽ có ở M2, sau khi các spike của Giai đoạn 0 trả lời được cách từng engine báo cáo kế hoạch dry-run.",
"docs": "Xem docs/ROADMAP.md"
}
}
+15
View File
@@ -0,0 +1,15 @@
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { App } from '@/App'
import '@/i18n'
import '@/styles.css'
const root = document.getElementById('root')
if (!root) throw new Error('missing #root element')
createRoot(root).render(
<StrictMode>
<App />
</StrictMode>,
)
+39
View File
@@ -0,0 +1,39 @@
/**
* Zustand stores — ARCHITECTURE §9.
*
* Five stores mirror the five domains the screens read: `useEnvStore`, `usePlanStore`,
* `useIndexStore`, `useSettingsStore`, `useHealthStore`. All engine data enters through the typed
* IPC wrappers in `@/ipc`; stores never call Tauri themselves.
*
* Only the settings store exists in Phase 0, because the app shell already needs a locale and an
* engine badge. The rest land in M2 with their screens.
*/
import { create } from 'zustand'
import { FALLBACK_LOCALE, type Locale } from '@/i18n'
/** Which resolver is active; shown in the status line (UI-SPEC §3). */
export type EngineId = 'pip' | 'uv'
interface SettingsState {
/** Active UI language. */
locale: Locale
/** Configured engine. First run pre-selects uv when it is on PATH (ARCHITECTURE §3). */
engine: EngineId
/**
* PEP 668 override. Off by default and deliberately hard to turn on — SECURITY §3 requires
* every mutating screen for such an env to show a persistent warning chip while it is set.
*/
allowExternallyManaged: boolean
setLocale: (locale: Locale) => void
setEngine: (engine: EngineId) => void
}
export const useSettingsStore = create<SettingsState>((set) => ({
locale: FALLBACK_LOCALE,
engine: 'pip',
allowExternallyManaged: false,
setLocale: (locale) => set({ locale }),
setEngine: (engine) => set({ engine }),
}))
+75
View File
@@ -0,0 +1,75 @@
@import 'tailwindcss';
/* Design tokens — UI-SPEC §2, "dark terminal-tech".
*
* Restrained phosphor-green on near-black, monospace where data lives, one accent doing real
* work. Anti-goals from that section: gradients-everywhere SaaS look, rounded-blob cards,
* decorative glow. Any glow is functional (focus rings, live-activity pulse) and subtle.
*
* Every text/surface pair here is asserted at WCAG AA by the contrast test in
* ui/src/tokens.test.ts (TESTING L3).
*/
@theme {
--color-bg: #0a0e0c;
--color-surface: #101612;
--color-surface-2: #161e18;
--color-border: #1f2b23;
--color-accent: #4ade80;
--color-accent-dim: #22935b;
--color-text: #e7f0ea;
--color-text-dim: #8aa394;
--color-warn: #f5b94a;
--color-danger: #f0574f;
--color-info: #5bc0de;
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, monospace;
--text-base: 0.875rem; /* 14px UI */
--text-data: 0.8125rem; /* 13px mono data */
--radius-pd: 6px;
/* UI-SPEC §2: motion is 120–160 ms ease-out. */
--ease-pd: cubic-bezier(0.16, 1, 0.3, 1);
}
@layer base {
html,
body,
#root {
height: 100%;
}
body {
background-color: var(--color-bg);
color: var(--color-text);
font-family: var(--font-sans);
font-size: var(--text-base);
}
/* UI-SPEC §8: the focus ring is 2px accent and is never removed. */
:focus-visible {
outline: 2px solid var(--color-accent);
outline-offset: 2px;
}
/* UI-SPEC §2: prefers-reduced-motion is respected. */
@media (prefers-reduced-motion: reduce) {
*,
*::before,
*::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
/* UI-SPEC §8: Windows high-contrast mode falls back to system colors. */
@media (forced-colors: active) {
body {
background-color: Canvas;
color: CanvasText;
}
}
}
+1
View File
@@ -0,0 +1 @@
import '@testing-library/jest-dom/vitest'
+50
View File
@@ -0,0 +1,50 @@
import { describe, expect, it } from 'vitest'
import {
AA_LARGE,
AA_NORMAL,
colors,
contrastRatio,
foregroundTokens,
surfaceTokens,
} from './tokens'
/**
* UI-SPEC §8: "all text tokens meet WCAG AA on their surfaces (verified in the design-token
* test)". This is that test — TESTING L3 lists it as a build-time gate, so a token tweak that
* quietly drops contrast fails CI rather than shipping.
*/
describe('design tokens', () => {
it.each(surfaceTokens)('primary text meets AA on %s', (surface) => {
expect(contrastRatio(colors.text, colors[surface])).toBeGreaterThanOrEqual(AA_NORMAL)
})
it.each(surfaceTokens)('dimmed text meets AA on %s', (surface) => {
// The "dimmed up-to-date rows" requirement (UI-SPEC §4) must stay readable, not decorative.
expect(contrastRatio(colors.textDim, colors[surface])).toBeGreaterThanOrEqual(AA_NORMAL)
})
it.each(['accent', 'warn', 'danger', 'info'] as const)(
'%s meets AA on the app background',
(token) => {
expect(contrastRatio(colors[token], colors.bg)).toBeGreaterThanOrEqual(AA_NORMAL)
},
)
it('accent-dim clears AA on the app background', () => {
// Secondary accents and links per UI-SPEC §2. It clears AA_NORMAL on --color-bg (4.99), so
// it is safe for body-size links there — but see the large-text sweep below for the darker
// ratio it gets on elevated surfaces.
expect(contrastRatio(colors.accentDim, colors.bg)).toBeGreaterThanOrEqual(AA_NORMAL)
})
it('every foreground token clears AA large on every surface', () => {
for (const fg of foregroundTokens) {
for (const surface of surfaceTokens) {
expect(
contrastRatio(colors[fg], colors[surface]),
`${fg} on ${surface}`,
).toBeGreaterThanOrEqual(AA_LARGE)
}
}
})
})
+71
View File
@@ -0,0 +1,71 @@
/**
* The UI-SPEC §2 design tokens, mirrored in TypeScript.
*
* `styles.css` is the runtime source of truth (Tailwind's `@theme` generates the utilities); this
* module exists so the contrast test in `tokens.test.ts` can assert WCAG AA over every text /
* surface pair without parsing CSS. The two must agree — the test checks that too.
*/
export const colors = {
bg: '#0A0E0C',
surface: '#101612',
surface2: '#161E18',
border: '#1F2B23',
accent: '#4ADE80',
accentDim: '#22935B',
text: '#E7F0EA',
textDim: '#8AA394',
warn: '#F5B94A',
danger: '#F0574F',
info: '#5BC0DE',
} as const
export type ColorToken = keyof typeof colors
/** Surfaces text can sit on. */
export const surfaceTokens = ['bg', 'surface', 'surface2'] as const
/** Tokens used for text and iconography. */
export const foregroundTokens = [
'accent',
'accentDim',
'text',
'textDim',
'warn',
'danger',
'info',
] as const
/** Parse `#RRGGBB` into 0–255 channels. */
export function toRgb(hex: string): [number, number, number] {
const v = hex.replace('#', '')
return [
Number.parseInt(v.slice(0, 2), 16),
Number.parseInt(v.slice(2, 4), 16),
Number.parseInt(v.slice(4, 6), 16),
]
}
/** Relative luminance per WCAG 2.1. */
export function luminance(hex: string): number {
const channel = (c: number) => {
const s = c / 255
return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
}
const [r, g, b] = toRgb(hex)
return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
}
/** WCAG contrast ratio between two colours, from 1 to 21. */
export function contrastRatio(a: string, b: string): number {
const la = luminance(a)
const lb = luminance(b)
const [hi, lo] = la > lb ? [la, lb] : [lb, la]
return (hi + 0.05) / (lo + 0.05)
}
/** WCAG AA for normal-size text. */
export const AA_NORMAL = 4.5
/** WCAG AA for large text (≥18.66px bold or ≥24px). */
export const AA_LARGE = 3
+38
View File
@@ -0,0 +1,38 @@
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
// The frontend lives in ui/ per ARCHITECTURE §2, but package.json sits at the repo root so the
// ops-repo `reusable-web-react.yml` — which has no working-directory input — can run `npm ci` and
// `npm run build` unmodified. Hence root: './ui' with the bundle emitted to the repo-root dist/,
// which is that workflow's default dist-dir.
export default defineConfig({
root: './ui',
plugins: [react(), tailwindcss()],
resolve: {
alias: {
'@': fileURLToPath(new URL('./ui/src', import.meta.url)),
},
},
build: {
outDir: '../dist',
emptyOutDir: true,
// Tauri ships its own WebView2; there is no legacy browser to support.
target: 'esnext',
sourcemap: true,
},
server: {
port: 1420,
// Fail loudly rather than silently moving ports — tauri.conf.json pins devUrl to 1420.
strictPort: true,
},
test: {
environment: 'jsdom',
globals: true,
setupFiles: [fileURLToPath(new URL('./ui/src/test/setup.ts', import.meta.url))],
include: ['ui/src/**/*.test.{ts,tsx}'],
root: fileURLToPath(new URL('.', import.meta.url)),
},
})