agentleFS
nasroykhnasroykh/foxmayn_frappe_cli/desktop/CLAUDE.md

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…

The file

Files
CLAUDE.md

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); job e2e (ubuntu, Chromium): Playwright and axe over every screen in en/fr/ar on the mock build, screenshots as the desktop-e2e artifact
  • .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 through wails3 update build-assets plus the APP_VERSION ldflags in the windows/darwin Taskfiles), then checksums.txt signed with relsign, provenance attestation and a prerelease with --latest=false
  • install-desktop.sh / install-desktop.ps1 — the desktop app: newest desktop-v<X.Y.Z> from the releases API (FFD_VERSION overrides), SHA-256 (+ signature with OpenSSL 3 on macOS, keys kept in sync by TestInstallScriptInSync), 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 import internal/ packages; renaming it to an unrelated path breaks that. Wails, Node and CGO must stay in desktop/go.mod, never in the root go.mod (the CLI release is CGO-free). Root go test ./.../go vet ./... skip it (desktop.yml runs them); root CI gofmt -l . does check its Go files. The root .gitignore entry for the foxmayn_frappe_cli binary is anchored (/foxmayn_frappe_cli) because unanchored it ignored the Wails bindings directory frontend/bindings/github.com/nasroykh/foxmayn_frappe_cli/. ffc update, the update check and the desktop installer never use GitHub's releases/latest (a desktop release may be it): release.Latest takes the newest non-draft, non-prerelease release whose tag is v<digit>…, so desktop releases need another tag prefix (e.g. desktop-v0.1.0). A desktop release must still be published with make_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.go holds one *cmd.MCPServer per engine key = site + EngineSpec hash (the canonical policy), with Policy.Confirm: always (ReadOnly in read mode); idle servers close after 10 minutes, never with a session open; each run gets its own in-process client named foxmayn-desktop and every call carries cmd.WithRunID. (2) Profiles (profiles.go: five presets, user copies) reach ffc only through MCPOptions, 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, and deny_tools and the call_method switch hold when tools are offered and when called. EngineSpec.canonical() copies the whole MCPPolicy, so a field ffc adds is carried (reflect test TestEngineSpecCanonicalCarriesEveryField); keep it that way. (3) The loop Classifyes each call: WillAsk means ffc's elicitation is the card (kind ffc, the app never answers it by itself); any other write needs an app card first, and update_doc reads the document, shows a field diff and sets if_unmodified to the read modified; bulk_update reads every document (bulkPrereadWorkers = 4 at once, at most cmd.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's modified, so Frappe refuses an item saved since (ffc words it "was changed on the server since", approvalBulkConflictHint); copy_doc/amend_doc read the source, list every field data sets next to the source's value (overrideFields, not a diff: a copy drops identity and "no copy" fields first, so docstatus or name equal to the source's is still a change; amend shows the amended_from ffc writes) and set if_unmodified, which ffc checks itself (a copy saves a new document, so Frappe checks nothing); a restore_doc card 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_method only when the profile, the mode and the site policy all allow it. (4) Every tool_use gets a tool_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.Message is the authoritative assistant turn stored in history, not the concatenated deltas. (5) Local-only (sitecontext.go, per-site setting): checkLocalOnly is the one check (loopback servers only, Ollama cloud-tagged models refused) and every path goes through it: NewConversation, SetConversationProfile, checkRun before a run and before each model turn (titles use the same provider path); checkRun also 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, the update_doc pre-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 through Keys (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 uses internal/loopback; the key is saved only in the keychain, never in events or errors. (9) llm/prices/prices.json is filled only from the providers' official pricing pages, each entry with its source and the table's price_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/bindings is 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 update lib/backend.ts, lib/backend-types.ts and mock/backend.ts with 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 through attach/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"> with escapeUntrusted and is stored as an attachment part (content, so the FTS index never sees it); images only when takesImages(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 with takesPDFs (Claude from 3.5) and dropDocuments, and for a model that reads them labelDocuments puts an untrusted <attachment> wrapper before each llm.Document and sends only the newest PDFs up to attach.MaxPDFBytes, older ones as notes; ImageData reads 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. EnableFileDrop is off; the composer reads each dropped File with the browser File API (which only hands a page what a person dropped or picked) and sends its bytes to AddDroppedFile (base64, attach.Parse, same limits); its drag handlers stop propagation so the Wails runtime listener on documentElement never sets dropEffect none. Never turn EnableFileDrop back on or accept a path from the web view. Only the native file dialog (AddAttachment) gives Go a path, and attach.ReadFile refuses UNC/device paths, on Windows anything but a drive-letter path (localVolume), and non-regular files. services/injection_test.go is 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 -race on macOS CI only (the Windows runner has no cgo); main and the test TestMain must call cmd.RunJQChildIfRequested() first. (14) Languages, RTL and accessibility (M3, 0.4.0). English, French, Arabic. i18n/index.ts detectLanguage (localStorage ffd-language, else the first of navigator.languages the app speaks, else en) is mirrored by public/theme-init.js, which sets lang/dir before the first paint: change both together. app/language.tsx gives Base UI the direction and calls AppService.SetLanguage, which picks the native file dialogs' strings (services/i18n.go dialogStrings, all three languages, TestDialogStrings). Every visible string, accessible name and toast goes through the catalog; en.json is the source, and fr.json/ar.json need 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 with intlLocale() (ar is ar-DZ-u-nu-latn, Latin digits), never toLocale* without a locale. A Go message the UI shows takes a key: keyed/keyedInvalid/CheckResult.setKeyed with errorKeys (English, equal to en.json errors.*: TestErrorKeysMatchCatalog; TestErrorKeysUsed reads the AST), Preview.ProblemKey; appError/localizedMessage translate, Detail stays 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.json rtl: true); Sidebar and Sheet side left/right mean start/end; index.css mirrors arrow and chevron icons in RTL (never add rtl:rotate on them), keeps .font-mono LTR and isolated, and gives text inputs unicode-bidi: plaintext; user text and each reply block get dir="auto". App shortcuts match letters on e.code and punctuation on e.key or e.code, and wait while a dialog is open and during the welcome. The pseudo-locale exists only in mock mode. frontend/e2e (desktop.yml job e2e, Chromium on ubuntu) runs a mock build under vite preview (the production CSP): a new screen or dialog gets an entry in e2e/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 the libc fields and the bindings/lockfile check fails. (15) Safety rules (services/policy.go; 0.7.0). Sites > Safety rules edits sites.<name>.mcp through config.File.SetSiteMCP under config.Edit (an empty policy removes the key). SavePolicy(name, base, p, opensConfirmed) refuses a base that differs from the file, and comparePolicies splits the change into opens and narrows; any opening change (read only off, a looser confirm, 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) needs opensConfirmed: the screen calls PreviewPolicy, shows its opens in an in-app AlertDialog (Cancel the default) and only then calls SavePolicy(name, base, p, true); without it the save is policy.confirmNeeded. base must 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, teach comparePolicies first: a widening classified as narrowing is saved without a question. Saves and removals serialise on policyMu. Rules the screen cannot show faithfully are refused: a blank deny entry (faithful), anchors, aliases or a << merge key in the site (File.SetSiteMCP); after SetSiteMCP the site is decoded again and must equal what was saved. TestSitePolicyCoversMCPPolicy fails when config.MCPPolicy gains 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; otherwise ChangeURL takes a newly typed NewSignIn (site.newServer when missing, NeedsSignIn tells the screen) of the kind authMethod reports (the order client.New follows) 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). SameServer compares 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.Query reads ffc's mcp-audit.jsonl and .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 through text.Sanitize and 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 what EngineSession.Call passes to cmd.WithRunID. The // i18n keys: comments in activity-screen.tsx list 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 one internal/desktopinstall finds (Find with AppVersion picks with NewestInstallable: the update check's Newest rule minus releases with a - suffix, which are only linked to. CheckForUpdate offers 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/status use Find too. A fresh install with no version uses Latest, which accepts flagged 0.x releases; a macOS/Windows copy whose version ffc desktop cannot read needs --force), the target is LocateSelf(os.Executable()) (an installed per-user exe on Windows; the .app outside /Volumes and AppTranslocation, writable, on macOS), and the file is the one Download verified (signature of checksums.txt, then the SHA-256; Apply refuses 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 and hdiutil 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). Apply removes the .old/.new of an earlier update first; the app's finishUpdate and nothing else calls CleanupOld (the CLI leaves .old beside the new copy: the app may be running from it). ChecksumFor refuses a second entry for the asset name. Cancel works until Apply starts (the call, and ffc desktop install, run it on context.WithoutCancel from there; .github/workflows/desktop.yml also runs the root internal/desktopinstall tests on macOS, including the real disk image one). Single-flight under updateMu (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>; then Host.Quit(); if the start fails the app stays open (update.relaunch). main.go accepts only --after-update <integer pid> after RunJQChildIfRequested(), waits at most 15 s for that pid, then CleanupOld; every other argument is ignored. Errors are keyed update.* (updateError maps the desktopinstall.Err* sentinels with errors.Is; keep the keys literal for TestErrorKeysUsed). The UI (update-install-dialog.tsx) asks first and warns when AssistantService.ActiveRuns() > 0 or a mounted composer holds unsent text (lib/unsent.ts, reported by chat-pane); UpdateInfo.CanInstall/InstallBlocked come from Eligible; InstallCommand stays as the fallback. Tests: self_update_test.go (fake GitHub with a generated release key, recorded Run and start).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.