Fix smarter. Ship faster. Fixora is the workspace you open when the code is already broken.
This is fixora-desktop — the Electron app and the framework-free core-* packages it is built from.
The blueprint is in docs/ and it is the source of truth. If the code and the blueprint disagree, one of them is a bug. Start with docs/README.md; if you disagree with something, start with the Decision Register.
Current state: PROJECT_STATUS.md · Hard-won context: PROJECT_MEMORY.md · What shipped: CHANGELOG.md
Not building Fixora, just using it? Start with the User Guide — install, add your own AI key, and run your first verified repair. The beta is BYOK (bring your own key) and free; a one-time Supporter license (LICENSING.md) funds development. Building the Windows installer: PACKAGING.md. How the beta was verified: BETA-ACCEPTANCE.md.
Fixora can comment on every pull request with the lint/type issues in the changed files, and update
that same comment on every push instead of spamming new ones. To add it to any repo, copy
.github/workflows/fixora-pr.yml and
scripts/pr-comment.mjs, then adjust the lint/typecheck commands to match
that repo. It needs no secrets beyond the GITHUB_TOKEN GitHub Actions already provides.
| Tool | Version | Why |
|---|---|---|
| Node | ≥ 22.12 | |
| pnpm | 11.12.0 | npm install -g pnpm@11.12.0 |
| gitleaks | any | The secret gate is not optional. winget install gitleaks |
pnpm install
pnpm dev # opens the hardened Electron window
pnpm run ci # every gate, exactly as CI runs them ← note: `run`, see below
pnpm run ci, notpnpm ci.ciis a built-in pnpm command that wipesnode_modulesand reinstalls. Ours is a script, so it needsrun.
| Command | Gate |
|---|---|
pnpm typecheck |
strict TS, no any, noUncheckedIndexedAccess |
pnpm lint |
typescript-eslint strict, --max-warnings 0 |
pnpm test |
Vitest |
pnpm gate:contrast |
WCAG 2.2 AA over every semantic colour pair, both themes |
pnpm gate:boundaries |
Invariant I1 — core-* never imports electron or react |
pnpm gate:adr |
docs/adr/ has not drifted from the decision register |
pnpm gate:electron |
Electronegativity — Electron misconfiguration |
pnpm gate:secrets |
gitleaks |
pnpm gate:audit |
dependency vulnerabilities |
pnpm adr:sync |
regenerate docs/adr/ after changing the register |
A gate that can be skipped is not a gate. None of these have an override (Repo §4).
- The capabilities are one pipeline.
Ground → Reason → Propose → Verify → Present, invoked with different task profiles. Adding a capability must never require touching the engine. (ADR-001) - The LLM reasons over evidence, never over vibes. Deterministic analysis produces the findings; the model explains and repairs them. (ADR-002)
- Every fix ships with its proof. Patches are applied to an overlay filesystem, re-checked and re-tested before the user ever sees them. (ADR-003)
- Code stays on the user's machine unless they say otherwise. (ADR-004)
If a change violates one of those four, it is wrong, however convenient.
packages/core-* MUST NOT import electron | react | any app code
Machine-enforced by dependency-cruiser and ESLint, blocking in CI. It looks like fussiness in month one
and pays for the whole project in year two — it is what makes a CLI, a GitHub Action and a VS Code
extension cost weeks instead of quarters.