frappe's half of the Nextcloud file picker
Archived, superseded by the frappe app’s attach from Nextcloud (
apps/flagship/frappe), which replaced the picker plug.
frappe’s half of the Nextcloud file picker
Section titled “frappe’s half of the Nextcloud file picker”Status: plug authored, bake item and guard OWED. Nothing here has run against a live bench; see Evidence for exactly what has run.
Surface delivered: apps/platform/frappe/nextcloudPicker.plug.yaml (new).
Everything else on this page is a diff somebody else has to land, because it
touches files that were outside this work’s surface.
1. The decisive question, answered: what IS the frappe shim?
Section titled “1. The decisive question, answered: what IS the frappe shim?”It is an in-DB Client Script document. Not a bench app, not a
site_config JS injection, not a Custom HTML Block, not a website_context
hook. The shim’s own first lines say so
(huly/bridges/nextcloud-picker/frappe-shim/nextcloud_upload_option.js:1-7):
// nextcloud-picker Frappe shim: the Client Script body (view=Form).// Adds a "Nextcloud" source to Frappe's attach dialog via the// frappe.ui.FileUploader.UploadOptions static registry ...// No app, no image rebuild: this rides the site DB as an in-DB// Client Script and therefore rides site backups too.and the bridge’s own status table agrees:
huly/bridges/nextcloud-picker/README.md:423:
frappe-shim/| Client Script body + idempotent headless provisioning over the REST API (OQ 14 route). Written from the registry inspection, not yet driven live
README.md:385-389 records the decision: “ERPNext, yes, and no app at all.”
The shim is a self-contained IIFE with one placeholder, __PICKER_ORIGIN__,
which its header says “is substituted by provision.py”. provision.py does
not exist; find over the whole bridge returns nothing and the only
reference to it in the tree is that comment. Substituting the placeholder and
landing the row is therefore net-new work, and it is what the plug does.
The four upstream facts the design is pinned to
Section titled “The four upstream facts the design is pinned to”Verified against a frappe version-15 checkout at
/var/tmp/frappe-arch/work/frappe-version-15 (frappe/__init__.py:54 →
__version__ = "15.117.0"; the pinned image carries framework 15.116.1 per
apps/platform/frappe/app.yaml).
| # | Fact | Source |
|---|---|---|
| 1 | frappe.ui.FileUploader.UploadOptions is a real static registry, and each entry’s action is invoked as action({dialog, uploader, doctype, docname, fieldname}), exactly the ctx the shim destructures | frappe/public/js/frappe/file_uploader/file_uploader.bundle.js:6, 69-77, 165 |
| 2 | Client Scripts are loaded per doctype and only when enabled: frappe.get_all("Client Script", filters={"dt": self.name, "enabled": 1}, ...). There is no wildcard dt and no global form. | frappe/desk/form/meta.py:144-155 |
| 3 | The doctype’s own schema: dt (Link→DocType, reqd, set_only_once), view (List|Form, set_only_once), enabled (Check, default 0), script (Code), autoname: "Prompt" / naming_rule: "Set by user" | frappe/custom/doctype/client_script/client_script.json |
| 4 | A prompt-autonamed doctype keeps a caller-supplied name and throws without one | frappe/model/naming.py:153 (if autoname.lower() != "prompt": doc.name = None) and :562-569 (_prompt_autoname) |
Fact 3 hides the nastiest trap in the whole integration: enabled defaults
to 0, and fact 2’s loader filters on enabled = 1. A row inserted without
an explicit enabled exists, looks right in the Desk list view, and renders
nothing. The plug writes it and reads it back.
The alternative that was rejected, and why: this one is a real finding
Section titled “The alternative that was rejected, and why: this one is a real finding”site_config.json does have a global Desk JS hook, and it is easy to
miss: frappe/www/app.py:get_context builds
include_js = hooks.get("app_include_js", []) + frappe.conf.get("app_include_js", [])frappe.conf is site_config.json + common_site_config.json, and
include_script → bundled_asset → abs_url
(frappe/utils/jinja_globals.py:98-138, frappe/website/utils.py:215-227)
renders each entry as a plain <script src> on every Desk page. That is
genuinely global, needs no bench app and no image rebuild, and would dissolve
the doctype-list problem below.
It was rejected on a measured ordering fact:
frappe/hooks.py:21-30puts frappe’s own bundles (libs,desk,list,form, …) inapp_include_js, soconfentries render after them; ordering is fine.- But
file_uploader.bundle.jsis not one of those bundles.desk.bundle.js:68importsfrappe/upload.js, whose entire body isfrappe.require("file_uploader.bundle.js"), andfrappe.require(frappe/public/js/frappe/assets.js:8-20) returns a Promise and loads asynchronously. - A
conf-injected<script>therefore runs before that promise settles, so the shim’s own first guard (if (!window.frappe || !frappe.ui || !frappe.ui.FileUploader) return) returns every time. The integration would be a silent no-op.
A Client Script runs at form render, long after boot, which is precisely why the shim is written as one.
A cross-origin <script src> pointing at the picker’s own host was rejected
outright and should stay rejected: it would make picker JavaScript same-origin
with Desk and hand it the user’s ERPNext session, dissolving the
origin/source/nonce/version isolation that the postMessage contract exists to
provide.
2. What the plug does
Section titled “2. What the plug does”apps/platform/frappe/nextcloudPicker.plug.yaml, consuming the
nextcloudPicker socket that apps/collaboration/nextcloud-picker publishes
(pickerUrl, the browser-facing origin to embed).
services: [frappe-web] # frappe never dials the picker from a container; # the integration is a browser popup + a MariaDB rowdata.consumer: frappedata.doctypes: "{{ vars.nextcloudPicker.doctypes | default('Sales Invoice,…') }}"
jobs.post_deployment[0] frappe-install-picker-client-script (context: service, frappe-web)jobs.unintegration[0] frappe-remove-picker-client-script (context: service, frappe-web)No vapp: key, deliberately and structurally: frappe plug mechanisms are
image-owned (owner ruling 2026-08-08) and tests.bats already pins that.
Top-level keys are services / data / jobs only, inside ce’s closed plug
key set (tests/unit/catalog/plug_key_readers_test.go:92-107), and every job
field used (name, context, service, command, environment, timeout)
is declared by the readers plugPostDeploymentJob / UnintegrationJob
(ce modules/app/plug_jobs.go:88-99, modules/app/unintegration_runner.go:125-141).
The apply job, in order
Section titled “The apply job, in order”pickerUrlempty → quiet no-op, exit 0 (the socket read is| default('')-guarded, per house doctrine for an unbound edge).- Split
pickerUrlinto scheme+host and tail. A path-routed picker is REFUSED (exit 1) rather than degraded; the shim carries one constant used both as theevent.origincomparand and as the popup URL base (nextcloud_upload_option.js:19, 50, 71), so a--host example.com/pickerinstall cannot be expressed: substituting the base breaks every origin check, substituting the origin 404s the popup, and both fail silently from the user’s side. A bare trailing/is accepted. - The baked shim missing → REFUSED, naming
IMAGE-OWNEDand the path. - One Python pass builds every
--kwargspayload from the real shim body. - Per site (
sites/*/site_config.json, skippingassets/common_site_config.json): two batch reads (which named doctypes exist, which of our rows exist), then per doctype an insert-or-update, then a read-back of the stored row asserting"enabled": 1and that the picker origin is present in the body that landed. - Rows for doctypes that have left the list are reaped: name-prefix scoped, so a hand-written Client Script on the same doctype is untouched.
- On success it prints the exact origin the operator must add to the picker’s
vars.allowedParentOrigins, derived from{{ url('frappe-web') }}.
Two things worth knowing about bench execute
Section titled “Two things worth knowing about bench execute”Both were verified in frappe/commands/utils.py:241-290 and both shape the job:
--kwargsis not parsed as JSON. The command runs the string through Python’s builtin expression evaluator. So a payload must be a valid Python literal as well as valid JSON;true/false/nullwould be aNameError. That is why the Check field is written asenabled: 1(int), and why the generator callsast.literal_evalon every payload it emits before writing it. Getting this wrong fails mid-reconcile, per site.- Output is
print(json.dumps(ret))with noindent, and nothing at all when the return value is falsy. Default separators mean"name": "…"(space after the colon), which is what the existingimap.plug.yamlread-back greps rely on, but the whole document is one line, so extracting several names needstr ',' '\n'beforesed. An emptyget_listprints nothing rather than[].
The doctype list is a default, not a discovery
Section titled “The doctype list is a default, not a discovery”Fact 2 above is the constraint: there is no global Client Script, so the option
appears on the doctypes the plug names and nowhere else. The shipped default is
eight (Sales Invoice, Purchase Invoice, Purchase Order, Sales Order, Quotation, Item, Customer, Supplier) chosen as where an ERPNext user attaches
an externally authored document, and kept short because each entry costs
bench-execute round trips (a full frappe boot each) at deploy time. Doctypes the
site does not have are skipped, so a frappe-only bench without ERPNext
reconciles zero rows and says so.
The plug already reads vars.nextcloudPicker.doctypes first, guarded. That
variable is not yet declared, so today the default is the only value and
--var nextcloudPicker.doctypes=… would be rejected as unknown. §4 has the
two-file diff that turns it on; the plug needs no edit when it lands.
3. OWED: the bake-list item
Section titled “3. OWED: the bake-list item”The mechanism is image-owned; the plug only configures. Three edits, all outside this work’s surface.
(a) Vendor the shim into shc. Copy
huly/bridges/nextcloud-picker/frappe-shim/nextcloud_upload_option.js
verbatim to:
frappe/docker/shims/nextcloud-picker/client-script.jsIt must keep the literal __PICKER_ORIGIN__ placeholder; the plug refuses a
file that has lost it, on the grounds that it is then not the shim this plug
knows how to configure.
(b) Bake it. In frappe/docker/Dockerfile, beside the existing
/opt/shc block (which already establishes /opt/shc as this image’s
non-volume home for packaging artifacts, and whose G20 rule (nothing may
write under sites/ or logs/) this respects):
USER rootRUN install -d -m 0755 -o frappe -g frappe /opt/shc/shims /opt/shc/shims/nextcloud-pickerCOPY --chmod=0444 --chown=frappe:frappe \ frappe/docker/shims/nextcloud-picker/client-script.js \ /opt/shc/shims/nextcloud-picker/client-script.jsUSER frappeRUN test -s /opt/shc/shims/nextcloud-picker/client-script.js; \ grep -q '__PICKER_ORIGIN__' /opt/shc/shims/nextcloud-picker/client-script.jsThe build context is the repo root (docker/docker-bake.hcl sets
context = ".."), which is why the COPY source is repo-relative.
(c) A drift guard is owed with it. The bridge has exactly this problem
already and solved it: huly-shim/contract.ts is a byte-for-byte copy of
src/picker/contract.ts, refreshed by make sync-contract, and make lint
fails on drift (bridge README §“huly-shim/contract.ts is a byte-for-byte
copy”). The vendored copy here needs the same treatment or it silently rots
against a bridge on a different release train. Cheapest form: a
tests/unit/ci guard asserting the vendored file still contains
__PICKER_ORIGIN__, pushes onto frappe.ui.FileUploader.UploadOptions, and
performs all four inbound checks (event.origin, event.source, nonce,
v).
4. OWED: the doctype variable (2 files, 2 lines)
Section titled “4. OWED: the doctype variable (2 files, 2 lines)”apps/platform/frappe/app.yaml, in the vars: block (a sibling of imap:):
nextcloudPicker: doctypes@string: Comma-separated doctypes that get the Nextcloud source in the attach dialog. A Client Script is per-doctype (frappe/desk/form/meta.py filters on dt with no wildcard), so this list IS the reach of the integrationapps/platform/frappe/vars.yaml, at the same nesting depth (the
vars_schema_parity_test.go guard requires both directions):
nextcloudPicker: doctypes: "Sales Invoice,Purchase Invoice,Purchase Order,Sales Order,Quotation,Item,Customer,Supplier"Keep the string identical to the plug’s inline default so the observable behaviour does not change on the commit that declares it.
5. OWED: the guard, for apps/platform/frappe/tests/tests.bats
Section titled “5. OWED: the guard, for apps/platform/frappe/tests/tests.bats”Add verbatim, next to the "imap plug ingests into ONE functional inbox" and
"no frappe plug declares a vapp dependency" tests it is modelled on. The
python body has been executed against the committed plug and prints OK.
@test "the nextcloud picker plug configures an in-DB Client Script, image-owned" { # The shim is a Client Script BODY (frappe-shim/nextcloud_upload_option.js # line 1; frappe/desk/form/meta.py:add_custom_script is the loader, and its # filter is dt-scoped with no wildcard AND requires enabled=1). So the plug # CONFIGURES a row while the IMAGE owns the file: no bench app, no vApp, # no site_config include (that route is a silent no-op: FileUploader is # frappe.require'd asynchronously, so a conf-injected script runs before it # exists). Guards, in the order they bite: # - no vapp:, and no top-level key outside ce's closed plug set; # - the socket read is default('')-guarded, so an unbound edge no-ops; # - the missing-bake refusal names IMAGE-OWNED and the baked path; # - enabled=1 is written AND read back; the doctype default is 0, and a # disabled row renders nothing while looking perfectly correct; # - a path-routed picker is REFUSED, never degraded: one shim constant # serves both the origin check and the popup URL; # - the teardown is name-prefix scoped, so it cannot eat a hand-written # Client Script sitting on the same doctype. run python3 -c "import yamldoc = yaml.safe_load(open('$SHC_APP_DIR/nextcloudPicker.plug.yaml'))assert set(doc) <= {'data', 'jobs', 'required', 'services', 'socket'}, sorted(doc)assert 'vapp' not in doc, 'frappe plug mechanisms are baked, never vdeployments'assert doc['services'] == ['frappe-web'], 'frappe never dials the picker'[apply] = doc['jobs']['post_deployment'][teardown] = doc['jobs']['unintegration']assert apply['name'] == 'frappe-install-picker-client-script'assert apply['context'] == 'service' and apply['service'] == 'frappe-web'env, cmd = apply['environment'], apply['command']assert \"| default('')\" in env['PICKER_URL'], 'an unbound edge must degrade quietly'assert 'bench get-app' not in cmd, 'runtime get-app is the 2026-08-05 outage path'assert 'install-app' not in cmd, 'no app installs belong in a picker edge'assert 'IMAGE-OWNED' in cmd, 'the missing-bake refusal must state the rule'assert '/opt/shc/shims/nextcloud-picker/client-script.js' in cmd, 'the baked path must be named'assert 'a path-routed picker' in cmd, 'one constant cannot serve origin AND base'assert 'Read back the STORED row' in cmd, 'read-back is house discipline'assert '\\\"enabled\\\": 1' in cmd, 'enabled DEFAULTS TO 0; the read-back must prove it is 1'assert 'view' in cmd and 'Client Script' in cmdtcmd = teardown['command']assert 'SHC Nextcloud Picker - ' in cmd and 'SHC Nextcloud Picker - ' in tcmd, 'both halves scope by one prefix'assert 'frappe.client.delete' in tcmdassert tcmd.rstrip().endswith('exit 0'), 'a failing disconnect never fails the teardown'print('OK')" [ "$status" -eq 0 ] printf '%s\n' "$output" | grep -q "OK"}6. OWED upstream, in the bridge
Section titled “6. OWED upstream, in the bridge”Neither is fixable from the plug without forking the shim.
__PICKER_BASE__alongside__PICKER_ORIGIN__. The shim uses one constant for two jobs:event.origin !== PICKER_ORIGIN(nextcloud_upload_option.js:71) andPICKER_ORIGIN + '/picker?…'(:50). Those are the same string only when the picker owns a whole host. Until the split lands, the plug refuses a path-routedpickerUrl; with it, the refusal becomes a substitution.- A retry around the
frappe.ui.FileUploaderguard (:25-27). As a Client Script the guard is almost always satisfied, because form render happens long after boot, but a hard refresh straight onto a form URL can still land beforefrappe.require("file_uploader.bundle.js")resolves, and the current code returns permanently. Re-checking inside the option’saction, or awaitingfrappe.requirebefore pushing, closes it.
Also still true and inherited from the bridge’s own status table: nothing in
src/nextcloud/, src/auth/tokenExchange.ts or the OIDC flow has ever seen a
live response. The first thing to verify live remains the token exchange for
audience=nextcloud (bridge README §10).
7. The two operator obligations this plug cannot discharge
Section titled “7. The two operator obligations this plug cannot discharge”Restated from apps/collaboration/nextcloud-picker/nextcloudPicker.socket.yaml,
because the socket says the consumer must handle them and the huly plug carries
the same paragraph:
- frappe’s public origin must be in the picker stack’s
vars.allowedParentOrigins. Exact match; an origin off the list is refused at postMessage time by design. The apply job prints the value to add on every successful run. - The audience obligation lives on the picker’s Keycloak client, not on frappe. The picker runs its own OIDC login in the popup and exchanges that token for the Nextcloud audience; nothing here mints or forwards a frappe token. The practical consequence for this consumer: frappe should be attached to the same realm, or the popup prompts a second, separate login instead of signing in silently.
Evidence
Section titled “Evidence”Nothing has run against a live bench. What has run:
-
Static. The file parses as YAML; both job bodies pass
sh -nafter the$$→$unescape; the embedded generator passesast.parse. Top-level keys and every job field are inside ce’s closed sets (§2). No{{/{%outside the four intended expressions. -
The generator, against the real shim. Dedupes and trims the doctype list, substitutes
__PICKER_ORIGIN__(6007-byte body, placeholder gone,'https://picker.example.com'present), and every emitted payload round trips throughast.literal_eval; the Python-literal constraint from §2 is proven, not assumed. -
The reconcile loop, against a fake
benchthat reproduces the two behaviours the job depends on (kwargs are a Python literal; output is un-indentedjson.dumps, nothing when falsy) and the doctype defaultenabled = 0. Eleven scenarios, all as intended:# scenario result 1 fresh install, one unknown doctype in the list 3 rows, unknown skipped, rc=02 re-run unchanged 3 rows, update path, rc=03 doctype removed from the list stale row reaped 4 a row disabled by hand enabledback to 15 pickerUrlwith a path prefixREFUSED, rc=16 pickerUrlwith a bare trailing/accepted 7 pickerUrlemptyquiet no-op, rc=08 baked shim absent REFUSED naming IMAGE-OWNED, rc=19 write silently ignored by the server caught by read-back, rc=110 unintegration beside a foreign Client Script only ours removed, foreign row intact 11 unintegration with nothing to do removed 0,rc=0Scenario 8 ran against the real
/opt/shc/...path; the other ten substituted the bridge’s shim path, since/optis not writable here. -
Not run:
go test ./tests/unit/catalog/is red on this worktree before and after this file;TestNoPlugDeclaresAnUnreadKeyaborts atplug_key_readers_test.go:249because its catalogue walk expectsapps/frappewhile the tree hasapps/platform/frappe. Confirmed pre-existing by removing this plug and re-running: identical failure. The closed-key-set assertions in §2 were therefore checked by hand against the reader structs rather than by the guard.