ffc-dev-client
Skill16 starsChanged 37 days agoMITView on GitHub
Change the ffc HTTP client, auth and config layer safely - internal/client (FrappeClient, do/send, hints and error classes, retries, redirects, raw and streamed requests, dry runs, debug redaction), API key / session / OAuth auth and token refresh, OAuth registration and revocation (internal/sitesetup), and config reads and writes (internal/config - config.Edit, locks, env overrides). Use it whenever you add a Frappe API call, touch authentication or login, change how requests are sent or retried, or write to config.yaml, and whenever Frappe answers in an unexpected shape. Load ffc-dev first.
- Reads credentials
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- desktop/CLAUDE.mdCLAUDE.md
- ffc-bulk-lifecycleSkill
- ffc-coreSkill
- 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
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Only GET (and HEAD) follow redirects.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Client, auth and config internals
These layers carry the security boundary (credentials never reach another host) and the exit-code contract. CLAUDE.md "Common Pitfalls" holds the detailed Frappe evidence; read the bullet for the area you touch.
Adding a Frappe API call
// client.go style: one method per Frappe call, ctx first, hints for 401/403/404.
func (c *FrappeClient) CreateDoc(ctx context.Context, doctype string, data map[string]interface{}) (map[string]interface{}, error) {
hints := readHints(doctype)
hints[http.StatusForbidden] = fmt.Sprintf("permission denied (403): your user may not have create access to %s", doctype)
var env dataEnvelope
if err := c.do(ctx, http.MethodPost, resourcePath(doctype), data, nil, hints, &env); err != nil {
return nil, c.missingDocType(ctx, doctype, err)
}
return env.doc() // a 2xx without "data" is an error, not an empty doc
}- Everything goes through
c.do(ctx, method, path, body, query, hints, out)→send: auth header per request, session relogin, OAuth refresh on 401, dry-run hold-back, debug trace, error conversion. Do not add a second request path. readHints(doctype)/docHints(doctype, name, access)give actionable 401/403/404 messages;docMethodmakes a 404 from a whitelisted method name the document, not the method.- Return the typed errors
classifyunderstands:*APIError(status +exc_type),*AuthError,*TransportError,*StateError(wrong document state, exit 6),*RedirectError. Messages come fromfrappeErrorResponse.userMessage(); non-JSON bodies are cut to 300 runes and sanitised. - A Frappe quirk you rely on gets a test against the fake and, when the fake cannot prove it, a contract test (ffc-dev-testing).
Frappe response shapes that trip people up: references/frappe-api-quirks.md.
Transport rules (http.go, raw.go, files.go)
- Only GET (and HEAD) follow redirects; a redirected write fails with the target URL. Never https → http, never another host while
AuthorizationorCookieis set. - Retries: GET only, on 429/502/503/504 and transport errors; never after timeout, cancel, refused redirect or TLS error; Retry-After honoured up to 10 s. Never add retries to writes.
Raw(used byffc api, downloads) is streamed with no retries and no 128 MiB cap;SitePathrefuses absolute and//hostURLs,CheckHeadersrefusesAuthorization,Cookie,Host,X-Frappe-Site-Name,X-Forwarded-Host. Keep both checks in the client.- Streamed downloads run the GET retry policy in their own loop (resty's retries leak a streamed body). Multipart uploads build a fresh streamed body per attempt inside
sendso a relogin replays it intact. - Non-site HTTP (GitHub releases) uses
client.NewHTTPClient(timeout), neverresty.New()(its logger printsWARN RESTYlines). - Anything that logs requests or plans uses the redaction helpers in debug.go (
TestDebugNeverPrintsSecretscovers all auth methods). Printed URLs go throughredactedURL.
Auth
| Method | Header | Picked when (in order) |
| OAuth | Authorization: Bearer <token> (attached per request in send) | cfg.AccessToken != "" (IsOAuth) |
| API key | Authorization: token key:secret | APIKey + APISecret |
| Password | Cookie: sid=... after a login inside client.New | IsSessionAuth() (username and password) |
client.Newis fallible (session sites log in). Commands get clients fromcallSite/newClient(internal/cmd/site_client.go):loadSite=loadSiteConfig(no network) + OAuth refresh under the config lock;newSiteClientadds the in-runtokenRefresher.- On a 401 an OAuth client probes
frappe.auth.get_logged_userwith the same token: only a refused token triggers one single-flight refresh and one repeat (writes included). A 401 raised by the method itself is returned, never retried. Definitive refresh failures (token endpoint 400/401/403, no refresh token) are remembered per token. - Session sites log in once per invocation and must log out (
CloseQuietly), or every run leaves a live session. Long-lived clients relogin on 401/403 only after checking the session is really gone. Never persist asid. 2FA is not supported (LoginPasswordreturns an error pointing to OAuth or an API key).
OAuth setup and revocation (internal/sitesetup)
- Prompt-free and cobra-free (the desktop app uses it);
internal/cmdkeeps forms, spinners and messages. - PKCE callback server binds
127.0.0.1(redirect URIhttp://127.0.0.1:<port>/callback, neverlocalhost), accepts exactly one result, answers duplicates with 409, always closes on abort. ResolveOAuthApp:--client-idas is; else dynamic registration when/.well-known/oauth-authorization-serverhasregistration_endpoint(Frappe v16): one public client, exactly this run's redirect URI, scopeopenid all, never twice per run; else*NoRegistrationError(wizard prompts for a client id; non-interactive setup turns it into a usage error naming--client-id). Posts only to the configured site's host.site removecallsRevokeToken(refresh token,client_idin the form, no Authorization header) before taking the config lock, bounded by 10 s, warning only on failure.
Config (internal/config)
- All writes go through
config.Edit(path, func(f *config.File) error {...})orconfig.Overwritefor a fresh file: lock (config.yaml.lock), re-read, edit theyaml.Nodetree (comments and key order survive), atomic write at 0600, symlinks followed. Returnconfig.ErrUnchangedto skip. Network calls while holding the lock stay withinconfig.MaxLockHold(30 s). Helpers onFile:Get,Set,HasSite,SiteNames,Site,PutSite,RemoveSite,RenameSite,SetSiteURL,SetSiteTokens. - Site writes from commands go through
siteStore(path)(sitesetup.Store), which also drops the site's cache (sitecache.Drop). - Reads:
config.Load(site, path)(env overrides applied) orconfig.Read(path);resolveCfgPath()for the path.Config/SiteConfighaveyamltags only;SiteConfig.Nameis runtime-only, the exact YAML key. - Site names keep case and dots; matching is exact, then unique case-insensitive. Do not reintroduce viper (it lowercased keys and split on dots).
- Env:
FFC_API_KEY+FFC_API_SECRETonly as a pair (replace stored credentials);FFC_URLonly with the pair, error alone when different; no config file → the three vars define the site.applyEnvOverridesandPutSitemust keep a site'smcpblock.
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.

