foxmayn_frappe_cli / desktop
CLAUDE.md16 starsChanged 37 days agoMITView on GitHub
Foxmayn Frappe Desktop (Wails v3 + React 19 + shadcn/ui on Base UI). Loaded when the work is under desktop/; the root CLAUDE.md covers the CLI. Layout and dev commands (npm run dev:mock, Windows and macOS only): desktop/README.md. Desktop release. Tag desktop-vX.Y.Z (not v*, so release.yml and GoReleaser ignore it) after writing desktop/release-notes/X.Y.Z.md (a default unsigned-beta text is used when it is missing). It is always --latest=false (install scripts and ffc <= v1.11.0 read releases/latest), and a prerelease for 0.x…
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ffc-bulk-lifecycleSkill
- ffc-coreSkill
- ffc-dev-clientSkill
- ffc-dev-commandSkill
- ffc-dev-desktopSkill
- ffc-dev-mcp-toolSkill
- ffc-devSkill
- ffc-dev-testingSkill
- ffc-files-collabSkill
- ffc-mcpSkill
- ffc-reports-apiSkill
- ffc-setupSkill
The file
Files
CLAUDE.md — desktop/
Foxmayn Frappe Desktop (Wails v3 + React 19 + shadcn/ui on Base UI). Loaded when the work is under desktop/; the root CLAUDE.md covers the CLI. Layout and dev commands (npm run dev:mock, Windows and macOS only): desktop/README.md.
Release
Desktop release. Tag desktop-vX.Y.Z (not v*, so release.yml and GoReleaser ignore it) after writing desktop/release-notes/X.Y.Z.md (a default unsigned-beta text is used when it is missing). It is always --latest=false (install scripts and ffc <= v1.11.0 read releases/latest), and a prerelease for 0.x or a - suffix.
Builds are unsigned until the secrets exist (APPLE_CERTIFICATE_P12_BASE64, APPLE_CERTIFICATE_PASSWORD, APPLE_ID, APPLE_TEAM_ID, APPLE_APP_PASSWORD; WINDOWS_CERTIFICATE_PFX_BASE64, WINDOWS_CERTIFICATE_PASSWORD); those signing steps have never run.
Workflows and install scripts:
.github/workflows/desktop.yml— desktop/ on windows-latest and macos-latest when desktop/, internal/ or go.mod change: npm ci, tsc + vite build,go mod tidy -diff, vet, tests,wails3 build(CLI version from desktop/go.mod), committed bindings and lockfile unchanged, govulncheck (macOS); jobe2e(ubuntu, Chromium): Playwright and axe over every screen in en/fr/ar on the mock build, screenshots as thedesktop-e2eartifact.github/workflows/desktop-release.yml—desktop-v*tags publish; a PR touching the file or desktop/build/**, and a manual run, are dry runs (artifacts only). Windows per-user NSIS installer and universal macOS dmg (version stamped throughwails3 update build-assetsplus theAPP_VERSIONldflags in the windows/darwin Taskfiles), then checksums.txt signed with relsign, provenance attestation and a prerelease with--latest=falseinstall-desktop.sh/install-desktop.ps1— the desktop app: newestdesktop-v<X.Y.Z>from the releases API (FFD_VERSIONoverrides), SHA-256 (+ signature with OpenSSL 3 on macOS, keys kept in sync byTestInstallScriptInSync), then the app to/Applications(or~/Applications) via hdiutil + ditto +codesign --verify, or the NSIS setup run with/S(per user). Closes only the installed copy. A curl/PowerShell download carries no quarantine/mark of the web, so the unsigned app skips Gatekeeper and SmartScreen; that is their purpose until the app is signed. The update notice runs them from the release tag (desktopInstallCommand)
Pitfalls
desktop/is a nested Go module (github.com/nasroykh/foxmayn_frappe_cli/desktop). Its path under the ffc module path is what lets it importinternal/packages; renaming it to an unrelated path breaks that. Wails, Node and CGO must stay indesktop/go.mod, never in the rootgo.mod(the CLI release is CGO-free). Rootgo test ./.../go vet ./...skip it (desktop.yml runs them); root CIgofmt -l .does check its Go files. The root.gitignoreentry for thefoxmayn_frappe_clibinary is anchored (/foxmayn_frappe_cli) because unanchored it ignored the Wails bindings directoryfrontend/bindings/github.com/nasroykh/foxmayn_frappe_cli/.ffc update, the update check and the desktop installer never use GitHub'sreleases/latest(a desktop release may be it):release.Latesttakes the newest non-draft, non-prerelease release whose tag isv<digit>…, so desktop releases need another tag prefix (e.g.desktop-v0.1.0). A desktop release must still be published withmake_latest: false(never GitHub's latest): install.sh (the releases/latest redirect), install.ps1 (the releases/latest API) and every ffc up to v1.11.0 still read releases/latest.- Desktop Assistant (0.3.0). Chat screen over the embedded ffc MCP server; plans in the vault (M1, M2). Rules to keep: (1)
engine.goholds one*cmd.MCPServerper engine key = site +EngineSpechash (the canonical policy), withPolicy.Confirm: always(ReadOnlyin read mode); idle servers close after 10 minutes, never with a session open; each run gets its own in-process client namedfoxmayn-desktopand every call carriescmd.WithRunID. (2) Profiles (profiles.go: five presets, user copies) reach ffc only throughMCPOptions, which only narrows the site policy: Confirm and ReadOnly are forced, stored loosening keys are ignored, unknown tool sets fail closed, write mode is the stricter of profile and conversation switch, anddeny_toolsand thecall_methodswitch hold when tools are offered and when called.EngineSpec.canonical()copies the wholeMCPPolicy, so a field ffc adds is carried (reflect testTestEngineSpecCanonicalCarriesEveryField); keep it that way. (3) The loopClassifyes each call:WillAskmeans ffc's elicitation is the card (kind ffc, the app never answers it by itself); any other write needs an app card first, andupdate_docreads the document, shows a field diff and setsif_unmodifiedto the readmodified;bulk_updatereads every document (bulkPrereadWorkers= 4 at once, at mostcmd.MaxMCPBulkItems, a name given twice refused, any failed read fails the call before a card), shows a diff per document (ChatApproval.Docs) and sets each item'smodified, so Frappe refuses an item saved since (ffc words it "was changed on the server since",approvalBulkConflictHint);copy_doc/amend_docread the source, list every fielddatasets next to the source's value (overrideFields, not a diff: a copy drops identity and "no copy" fields first, sodocstatusornameequal to the source's is still a change; amend shows theamended_fromffc writes) and setif_unmodified, which ffc checks itself (a copy saves a new document, so Frappe checks nothing); arestore_doccard that names only the Deleted Document reads it first and adds the DocType and name it brings back (best effort,restoreTarget). Read mode does not offer write tools;call_methodonly when the profile, the mode and the site policy all allow it. (4) Everytool_usegets atool_result(declined, stopped, unknown tool, error); results are cut to 40 000 chars for the model; the step limit (profile, 1-100, default 25) pauses the run until Continue. Stop cancels the run ctx and declines open cards.llm.Stop.Messageis the authoritative assistant turn stored in history, not the concatenated deltas. (5) Local-only (sitecontext.go, per-site setting):checkLocalOnlyis the one check (loopback servers only, Ollamacloud-tagged models refused) and every path goes through it:NewConversation,SetConversationProfile,checkRunbefore a run and before each model turn (titles use the same provider path);checkRunalso refuses a conversation whose site address changed. Site settings carry over only from names no longer in the ffc config. (6) Text from outside the model's own turns is untrusted: tool results, theupdate_docpre-read error,<site_context untrusted="true">and<imported_history untrusted="true">are wrapped with every<escaped (escapeUntrusted); stored bytes replay unchanged. Import is never trusted: the conversation starts read only, the file's messages fold into one escaped block (never replayed as turns), site context is discarded, ids are made anew, 50 MB cap. (7) Store migration 2 holds all M2 schema (profiles, conversation columns, site_settings, usage cost columns with PRIMARY KEY (run_id, turn, kind), attachments, settings) in one transaction; a failed step rolls back to v1. Add later schema as migration 3+, never edit applied ones. (8) Provider keys live only in the OS keychain throughKeys(service "Foxmayn Frappe Desktop", user = provider id); events, the store, logs, exports and bindings carry at most the last 4. Adapters build their SDK service directly: they never read provider env vars (ANTHROPIC_*,OPENAI_*) and never follow redirects; Anthropic, OpenRouter, OpenAI and Gemini are pinned to their official hosts, and changing a provider's address deletes its key. The OpenRouter sign-in usesinternal/loopback; the key is saved only in the keychain, never in events or errors. (9)llm/prices/prices.jsonis filled only from the providers' official pricing pages, each entry with itssourceand the table'sprice_date; a model not in it costs "unknown", never a guess; provider-reported cost wins, loopback servers are tokens only. (10) Title: one call after the first completed run, single-flight per conversation (startTitle), cancelled on delete, skipped for ephemeral or user-named conversations. (11)frontend/bindingsis generated (wails3 generate bindings -clean=true -ts -i) and committed; desktop.yml fails on a diff, so regenerate after any Go service surface change, and updatelib/backend.ts,lib/backend-types.tsandmock/backend.tswith it. (12) Attachments (desktop/attach,services/attachments.go): every file is sniffed and checked in Go (attach.ReadFile/ParseImage: type by content and extension, 10 MB, 5 per message, 200 000/400 000 characters, XLSX through excelize, 16 MB unpacked in all and 8 MB a part, checked from the zip headers before excelize opens it (xlsxSizes), with sheet/row/cell caps, DOCX text throughattach/docx.go(32 MB unzip cap, XML depth and token budget, runs only: property subtrees,mc:Fallback, hidden and deleted text skipped), PDF kept as bytes and never parsed in the app (encrypted refused, 15 MB a message)); text goes to the model as<attachment name=… untrusted="true">withescapeUntrustedand is stored as anattachmentpart (content, so the FTS index never sees it); images only whentakesImages(kind, model)says the model reads them (OpenRouter and local: none), otherwise refused at send and replaced by a note in history (dropImages); PDFs likewise withtakesPDFs(Claude from 3.5) anddropDocuments, and for a model that reads themlabelDocumentsputs an untrusted<attachment>wrapper before eachllm.Documentand sends only the newest PDFs up toattach.MaxPDFBytes, older ones as notes;ImageDatareads only the conversation's own attachments. Dropped files never reach Go as paths (0.9.0): Wails beta.28 sends every native drop through JS and back (runtime method WindowFilesDropped), so a script in the web view could name any path.EnableFileDropis off; the composer reads each droppedFilewith the browser File API (which only hands a page what a person dropped or picked) and sends its bytes toAddDroppedFile(base64,attach.Parse, same limits); its drag handlers stop propagation so the Wails runtime listener on documentElement never sets dropEffect none. Never turnEnableFileDropback on or accept a path from the web view. Only the native file dialog (AddAttachment) gives Go a path, andattach.ReadFilerefuses UNC/device paths, on Windows anything but a drive-letter path (localVolume), and non-regular files.services/injection_test.gois the prompt-injection suite (hostile site text, tool results, attachments, imports against every guard); a new path for outside text gets a case there. (13) Desktop tests run-raceon macOS CI only (the Windows runner has no cgo);mainand the testTestMainmust callcmd.RunJQChildIfRequested()first. (14) Languages, RTL and accessibility (M3, 0.4.0). English, French, Arabic.i18n/index.tsdetectLanguage(localStorageffd-language, else the first ofnavigator.languagesthe app speaks, else en) is mirrored bypublic/theme-init.js, which setslang/dirbefore the first paint: change both together.app/language.tsxgives Base UI the direction and callsAppService.SetLanguage, which picks the native file dialogs' strings (services/i18n.godialogStrings, all three languages,TestDialogStrings). Every visible string, accessible name and toast goes through the catalog;en.jsonis the source, andfr.json/ar.jsonneed every key, every plural category of their language (fr one/many/other, ar all six: a missing form falls back to English) and the same{{vars}}and<tags>(i18n-parity.test.ts). Keys built at run time are listed in a// i18n keys:comment, which the test checks. Format withintlLocale()(ar isar-DZ-u-nu-latn, Latin digits), nevertoLocale*without a locale. A Go message the UI shows takes a key:keyed/keyedInvalid/CheckResult.setKeyedwitherrorKeys(English, equal to en.jsonerrors.*:TestErrorKeysMatchCatalog;TestErrorKeysUsedreads the AST),Preview.ProblemKey;appError/localizedMessagetranslate,Detailstays English. Restart hints are translated by client id in the UI (appHint; English shows Go's text as is). Model-facing prompts stay English, with one line asking for replies in the user's language. RTL: logical properties only (ms/me/ps/pe/start/end/text-start/border-s/border-e; components.jsonrtl: true); Sidebar and Sheetsideleft/right mean start/end; index.css mirrors arrow and chevron icons in RTL (never addrtl:rotateon them), keeps.font-monoLTR and isolated, and gives text inputsunicode-bidi: plaintext; user text and each reply block getdir="auto". App shortcuts match letters one.codeand punctuation one.keyore.code, and wait while a dialog is open and during the welcome. The pseudo-locale exists only in mock mode.frontend/e2e(desktop.yml jobe2e, Chromium on ubuntu) runs a mock build undervite preview(the production CSP): a new screen or dialog gets an entry ine2e/states.ts, and the clipped-text check, axe (serious and critical) and the pseudo-locale allowlist (exact strings only) stay green. Write the lockfile with npm 11 (npx npm@11 install): npm 10 drops thelibcfields and the bindings/lockfile check fails. (15) Safety rules (services/policy.go; 0.7.0). Sites > Safety rules editssites.<name>.mcpthroughconfig.File.SetSiteMCPunderconfig.Edit(an empty policy removes the key).SavePolicy(name, base, p, opensConfirmed)refuses abasethat differs from the file, andcomparePoliciessplits the change into opens and narrows; any opening change (read only off, a looserconfirm, an allow list lifted or widened, a deny entry removed, a sensitive DocType added to allow_doctypes (cmd.SensitiveDoctype), an allow_methods entry that unlocks a denied method (cmd.UnlocksDeniedMethod, wildcards included), call_method re-enabled because allow_doctypes-without-allow_methods stops holding) needsopensConfirmed: the screen callsPreviewPolicy, shows its opens in an in-app AlertDialog (Cancel the default) and only then callsSavePolicy(name, base, p, true); without it the save ispolicy.confirmNeeded.basemust equal the file, and the file is checked again under the lock. Entries compare exactly (a respelling asks). When ffc adds a policy field or a rule that unlocks something, teachcomparePoliciesfirst: a widening classified as narrowing is saved without a question. Saves and removals serialise onpolicyMu. Rules the screen cannot show faithfully are refused: a blank deny entry (faithful), anchors, aliases or a<<merge key in the site (File.SetSiteMCP); afterSetSiteMCPthe site is decoded again and must equal what was saved.TestSitePolicyCoversMCPPolicyfails whenconfig.MCPPolicygains a field. Confirmations are in-app (0.9.0, ADR-005). The native dialogs (policy_dialog.go, native_question.go,SiteConfirmer) are gone: a dialog in the web view proves what was shown, not that a person clicked, so safety comes from removing what a script could abuse, not from the dialog. Changing a site's address never sends its saved sign-in to another server:SameServer(same host and port, http to https allowed, https to http not) keeps it; otherwiseChangeURLtakes a newly typedNewSignIn(site.newServerwhen missing,NeedsSignIntells the screen) of the kindauthMethodreports (the orderclient.Newfollows) and saves a site holding only that sign-in and the new URL (sitesetup.Store.Move: no old key, password, token or OAuth client is carried, the mcp block stays, and a site removed or moved during the check is not written back).SameServercompares ASCII host names only. Replacing a site, removing a site with rules and turning Local models only off are asked in AlertDialogs by the screen; Go does not gate them. A script in the web view can still loosen rules or turn Local models only off; that is accepted in ADR-005. Never add a path where the window can make Go send a saved secret or read a file it names. (16) Activity (services/activity.go; 0.7.0).ActivityService.Queryreads ffc'smcp-audit.jsonland.1(never writes or clears), newest first, with filters (site, client, tool, status, run id, time) and paging. A log that is not a regular file is refused (Lstat), a file over 16 MiB is read from its end, a line over 64 KiB or that does not parse is skipped and counted, and every string of an entry (arguments included, keys too) goes throughtext.Sanitizeand is cut. The page lists the filter values from the whole log. The chat's "See activity" link filters by the Assistant run id (RunUsage.runID), which is whatEngineSession.Callpasses tocmd.WithRunID. The// i18n keys:comments inactivity-screen.tsxlist the status and confirmation keys. (17) Self-update (0.10.0; plan DV12).AppService.InstallUpdate(ctx)takes NO input from the web view: the release is the oneinternal/desktopinstallfinds (FindwithAppVersionpicks withNewestInstallable: the update check'sNewestrule minus releases with a-suffix, which are only linked to.CheckForUpdateoffers that same pick whenever it is newer than the app, even if a newer rc exists, so the version in the dialog is the one installed;ffc desktop install/statususeFindtoo. A fresh install with no version usesLatest, which accepts flagged 0.x releases; a macOS/Windows copy whose versionffc desktopcannot read needs--force), the target isLocateSelf(os.Executable())(an installed per-user exe on Windows; the.appoutside /Volumes and AppTranslocation, writable, on macOS), and the file is the oneDownloadverified (signature ofchecksums.txt, then the SHA-256;Applyrefuses any other path and holds a locked handle on Windows). The download goes to a private temp dir (NewTempDir, 0700 under the user cache folder) removed afterwards; the old copy stays until the new one is verified (macOS.old, Windows exe renamed aside) and a failure installs nothing: on Windows any setup failure (exit code, timeout) discards whatever new exe exists and renames the old one back. Same-user races on macOS between hashing the dmg andhdiutil attach(TOCTOU) are accepted: the dir is private to the user, and malware running as that user is out of scope. The tools run by absolute path (/usr/bin/hdiutil,ditto,codesign,plutil,xattr).Applyremoves the.old/.newof an earlier update first; the app'sfinishUpdateand nothing else callsCleanupOld(the CLI leaves.oldbeside the new copy: the app may be running from it).ChecksumForrefuses a second entry for the asset name. Cancel works untilApplystarts (the call, andffc desktop install, run it oncontext.WithoutCancelfrom there;.github/workflows/desktop.ymlalso runs the rootinternal/desktopinstalltests on macOS, including the real disk image one). Single-flight underupdateMu(update.busy). The relaunch path is always Go's own: macOS/usr/bin/open -n <bundle> --args --after-update <pid>, Windows<exe> --after-update <pid>; thenHost.Quit(); if the start fails the app stays open (update.relaunch).main.goaccepts only--after-update <integer pid>afterRunJQChildIfRequested(), waits at most 15 s for that pid, thenCleanupOld; every other argument is ignored. Errors are keyedupdate.*(updateErrormaps thedesktopinstall.Err*sentinels witherrors.Is; keep the keys literal forTestErrorKeysUsed). The UI (update-install-dialog.tsx) asks first and warns whenAssistantService.ActiveRuns() > 0or a mounted composer holds unsent text (lib/unsent.ts, reported by chat-pane);UpdateInfo.CanInstall/InstallBlockedcome fromEligible;InstallCommandstays as the fallback. Tests:self_update_test.go(fake GitHub with a generated release key, recordedRunandstart).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

