Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
F

fantasia-archive

> 编程语言
Open source

A world-builder's best friend!

399 stars0 likes0 views
WebsiteGitHub

About

A world-builder's best friend!

Fantasia Archive (fantasia-archive)

Worldbuilding database manager — Quasar + Vue 3 + Electron (GPL-3.0).

Yarn 1.x (CI pins [email protected]). Node.js 22.22.0+ (package.json engines.node). Match 22.22 locally to align with CI (.github/workflows/build.yml).

Playwright runs against production build under dist/electron, not quasar dev. Rebuild after src/, src-electron/, src/stores/, or i18n/*/documents/*.md changes:

yarn quasar:build:electron

Agent/maintainer guidance: AGENTS.md. Architecture depth → AGENTS + .cursor/skills/.

Install Quasar CLI

https://quasar.dev/start/quasar-cli — ensure Yarn global bin is on PATH.

bash
yarn global add @quasar/cli

Install dependencies

yarn

Git hooks: prepare runs husky; .husky/commit-msg → yarn lint:commit. Emergency bypass: git commit --no-verify (sparingly).

Optional: Caveman ecosystem (AI)

Not required to build/run app. caveman compressed agent replies — .cursor/rules/caveman-default.mdc. YAGNI minimal implementation — .cursor/rules/yagni.mdc. cavemem cross-session memory — global install + .cursor/hooks.json. Arbor (optional MCP code graph) — local gitignored .cursor/mcp.json (arbor.exe bridge), fantasia-arbor. Setup cavemem:

bash
npm install -g cavemem
cavemem install --ide cursor
cavemem doctor

Restart Cursor. Details: AGENTS.md.

Contributing

CONTRIBUTING.md — fork/PR workflow, labels, Storybook VRT on forks.

Architecture (pointers)

Topic Where
Two-level functions/ + *_manager.ts; *Wiring.ts for DOM/window/fs; domain barrels — see AGENTS.md Domain script barrels fa-two-level-architecture.mdc, fantasia-two-level-architecture
TypeScript strict (quasar.config.ts) eslint-typescript.mdc
YAGNI / minimal diffs yagni.mdc, fantasia-yagni
Trees (@he-tree/vue only; QTree forbidden) fa-he-tree.mdc, fantasia-he-tree
Floating Window* shared families fantasia-floating-windows (_sharedWindowStyling/, _sharedWindowNoteboard/)
List/table DnD fa-drag-drop-lists.mdc, fantasia-drag-drop
Reusable elements/ inputs AGENTS.md subsystems — FaSelectInput, FaIconPickerInput, FaLocaleTranslationsInput, FaColorPickerInput
Electron / IPC / preload; main security hardening AGENTS.md, fantasia-electron-main, fantasia-electron-preload
Keybinds, actions, Project Settings AGENTS.md subsystem table
SCSS / theme tokens project-scss.mdc
types/ shared interfaces types-folder.mdc only

Component buckets under src/components/: dialogs/, floatingWindows/, globals/, elements/, projectUI/, other/, foundation/ (Storybook-only). Five infra helpers use _ prefix — see AGENTS.md Renderer components.

Dev and build

bash
quasar dev -m electron
# or
yarn quasar:dev:electron

Production build:

bash
yarn quasar:build:electron

After packaging, Help → Toggle developer tools (or default F12 chord) must open DevTools — intentional product behavior in installed builds (fantasia-electron-main Packaged DevTools).

Quiet build (log → test-results/quasar-build-electron-last.log on failure):

bash
yarn quasar:build:electron:summarized

Electron + Storybook in one terminal:

bash
yarn app:dev

Release build (CI): the manual Build App workflow (.github/workflows/build.yml, workflow_dispatch with a version input) packages the production Electron app for Windows, macOS, and Linux (AppImage, deb, rpm) and uploads the installers. It runs no test gate — verify, Playwright, and Storybook VRT are not executed in CI. Run the full local gate first:

bash
yarn testbatch:ensure:nochange   # or testbatch:ensure:change when refreshing VRT baselines

Only trigger the CI build after that passes on your machine. Push/PR testing stays in .github/workflows/verify.yml (yarn testbatch:verify) and the pr-full-suite-* labeled-PR workflows.

Storybook

bash
yarn storybook:run
yarn storybook:build
yarn test:storybook:visual
yarn test:storybook:visual:update

Stories: src/**/_tests/*.stories.ts. Workspace: .storybook-workspace/. VRT policy: fantasia-testing, storybook-stories.mdc.

Quality gates

During development (agents and fast iteration)

Default after substantive edits: dev scoped gate — eslint on touched paths, yarn lint:typescript, stylelint on touched styles, yarn vitest run on connected specs only. Playbook: fantasia-dev-scoped-verify, dev-scoped-verify.mdc.

Agents also run 20s yarn quasar:dev:electron compile smoke after scoped gate (dev-electron-compile-check.mdc).

Full gate (before commit / final cleanup / CI)

bash
yarn testbatch:verify

Lint (repo) + vue-tsc + Stylelint + Vitest coverage (per file: 95% / 80% / 100% / 95% via thresholds.perFile: true on src-electron, helpers/, i18n/, renderer src .ts, component .ts + .vue). Debug one step, then re-run full gate.

When required: git commit, fantasia-final-cleanup, explicit full-verify request, push/PR CI. Dev scoped gate does not substitute.

Changelog-only exception: only i18n/*/documents/changeLog.md after full gate passed on substantive work — see testing-terminal-isolation.mdc.

CI Verify (.github/workflows/verify.yml): yarn testbatch:verify only — not Playwright, Electron prod build, or Storybook VRT.

Full chained gate:

bash
yarn testbatch:ensure:nochange   # compare VRT snapshots
yarn testbatch:ensure:change     # refresh VRT baselines (intentional UI only)

Testing

Vitest

bash
yarn test:unit
yarn test:coverage:verify

Workspace: vitest.config.mts → vitest/ projects (unit-electron, unit-src-renderer, unit-helpers, unit-i18n, unit-components).

Playwright (rebuild first)

Isolated userData: %APPDATA%/fantasia-archive/playwright-user-data. Serial suites reset via helpers/playwrightHelpers_universal/playwrightUserDataReset.ts.

bash
yarn test:components
yarn test:components:single --component=dialogs/DialogAppSettings
yarn test:components:list
yarn test:e2e
yarn test:e2e:single --spec=checkDevToolsFunctionality
yarn test:e2e:single:ci --spec=checkDevToolsFunctionality.playwright.spec.ts
yarn test:e2e:list

yarn test:components: src/components, src/layouts, src/pages (*.playwright.test.ts). Workspace E2E: e2e-tests/checkWorkspace*.playwright.spec.ts + helpers/playwrightHelpers_e2e/e2eWorkspaceHierarchyTree*.

Locators: data-test-locator + selectorList — playwright-tests.mdc. Keyboard: faPlaywrightKeyboardChords for cross-OS chords.

Report/videos: test-results/playwright-report/index.html. FA_PLAYWRIGHT_NO_VIDEO=1 to skip recording.

Scripts reference (package.json)

Script Purpose
Dev scoped gate (agents) fantasia-dev-scoped-verify — touched lint + connected Vitest; not one yarn script
yarn quasar:build:electron Production Electron build (full log).
yarn quasar:build:electron:summarized Same; quiet success; log file on failure.
yarn quasar:dev:electron Electron dev mode.
yarn app:dev Dev + Storybook parallel.
yarn lint:eslint ESLint.
yarn lint:stylelint / lint:stylelint:fix Stylelint on src/ + Storybook SCSS.
yarn lint:typescript vue-tsc project check.
yarn testbatch:verify Full pre-commit / CI gate (lint + types + style + coverage).
yarn testbatch:ensure:nochange Full gate + build + Playwright + Storybook VRT compare.
yarn testbatch:ensure:change Same; update VRT snapshots.
yarn test:unit Vitest (no coverage).
yarn test:coverage:verify Coverage tiers (same as verify Vitest step).
yarn test:coverage:electron / helpers / i18n / src Single coverage slice.
yarn test:components / test:e2e Playwright suites.
yarn test:storybook:smoke / visual* Storybook checks.
yarn storybook:run / storybook:build Storybook dev/static.
yarn audit:policy Heuristic policy report (not CI).
yarn audit:scss-literals Consumer SCSS literal audit (not CI).
yarn audit:domain-policy Domain policy grep (not CI).
yarn audit:quasar-component-tokens $q* token audit.
yarn audit:quasar-variables Feature styles/_variables.scss unused-$ audit.
yarn audit:full Chained local audits (not CI).
yarn audit:yagni YAGNI inventory + heuristic scan (not CI).
yarn audit:yagni:full YAGNI scan + optional jscpd/depcheck.
yarn audit:yagni:triage Mechanical per-file YAGNI triage JSON.
yarn generate:icon-catalogs Regenerate FaIconPickerInput catalogs.

Utility scripts (.utility-scripts/)

Script Role
quasarBuildElectronSummarized.mjs Summarized Electron build
playwrightWithArtifactTrim.mjs Playwright wrapper + artifact trim
auditQuasarComponentTokens.mjs Quasar component token audit
auditQuasarVariablesUsage.mjs Feature _variables.scss unused-$ audit
auditScssConsumerLiterals.mjs Consumer SCSS literal audit
domainPolicyGrep.mjs Domain policy grep
runFullProjectAudit.mjs Chained local audits
generateFaQuasarIconCatalogs.mjs Icon catalog generation
policyComplianceAudit.mjs Policy audit
auditYagni.mjs / auditYagniFullTriage.mjs YAGNI scan + full triage
syncI18nLocaleTreeFromEnUs.mjs Locale tree sync (maintainer)
batchTranslateI18nLocales.mjs Batch translate (maintainer)

Configuration

Quasar config — quasar.config.ts. tsconfig.json extends .quasar/tsconfig.json.

Native modules (better-sqlite3)

After Electron/Node version changes: clean yarn install (postinstall → electron-builder install-app-deps). If bindings missing: yarn rebuild:native, then retry dev/build.

Project databases (.faproject)

SQLite per project; schema user_version max 11 — docs/database/projectDB.md. Template custom fields design: templateCustomFields.md.

Project settings refresh: DialogProjectSettings IPC-reads on open (**`getProjectSe

Issues· 1 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

TypeScript

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言