Skip to content
SHC Docs

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).

#FactSource
1frappe.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 destructuresfrappe/public/js/frappe/file_uploader/file_uploader.bundle.js:6, 69-77, 165
2Client 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
3The 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
4A prompt-autonamed doctype keeps a caller-supplied name and throws without onefrappe/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-30 puts frappe’s own bundles (libs, desk, list, form, …) in app_include_js, so conf entries render after them; ordering is fine.
  • But file_uploader.bundle.js is not one of those bundles. desk.bundle.js:68 imports frappe/upload.js, whose entire body is frappe.require("file_uploader.bundle.js"), and frappe.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.


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 row
data.consumer: frappe
data.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).

  1. pickerUrl empty → quiet no-op, exit 0 (the socket read is | default('')-guarded, per house doctrine for an unbound edge).
  2. Split pickerUrl into scheme+host and tail. A path-routed picker is REFUSED (exit 1) rather than degraded; the shim carries one constant used both as the event.origin comparand and as the popup URL base (nextcloud_upload_option.js:19, 50, 71), so a --host example.com/picker install 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.
  3. The baked shim missing → REFUSED, naming IMAGE-OWNED and the path.
  4. One Python pass builds every --kwargs payload from the real shim body.
  5. Per site (sites/*/site_config.json, skipping assets / 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": 1 and that the picker origin is present in the body that landed.
  6. 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.
  7. 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:

  • --kwargs is 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/null would be a NameError. That is why the Check field is written as enabled: 1 (int), and why the generator calls ast.literal_eval on every payload it emits before writing it. Getting this wrong fails mid-reconcile, per site.
  • Output is print(json.dumps(ret)) with no indent, and nothing at all when the return value is falsy. Default separators mean "name": "…" (space after the colon), which is what the existing imap.plug.yaml read-back greps rely on, but the whole document is one line, so extracting several names needs tr ',' '\n' before sed. An empty get_list prints 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.


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.js

It 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 root
RUN install -d -m 0755 -o frappe -g frappe /opt/shc/shims /opt/shc/shims/nextcloud-picker
COPY --chmod=0444 --chown=frappe:frappe \
frappe/docker/shims/nextcloud-picker/client-script.js \
/opt/shc/shims/nextcloud-picker/client-script.js
USER frappe
RUN test -s /opt/shc/shims/nextcloud-picker/client-script.js; \
grep -q '__PICKER_ORIGIN__' /opt/shc/shims/nextcloud-picker/client-script.js

The 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 integration

apps/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 yaml
doc = 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 cmd
tcmd = 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 tcmd
assert tcmd.rstrip().endswith('exit 0'), 'a failing disconnect never fails the teardown'
print('OK')
"
[ "$status" -eq 0 ]
printf '%s\n' "$output" | grep -q "OK"
}

Neither is fixable from the plug without forking the shim.

  1. __PICKER_BASE__ alongside __PICKER_ORIGIN__. The shim uses one constant for two jobs: event.origin !== PICKER_ORIGIN (nextcloud_upload_option.js:71) and PICKER_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-routed pickerUrl; with it, the refusal becomes a substitution.
  2. A retry around the frappe.ui.FileUploader guard (: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 before frappe.require("file_uploader.bundle.js") resolves, and the current code returns permanently. Re-checking inside the option’s action, or awaiting frappe.require before 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:

  1. 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.
  2. 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.

Nothing has run against a live bench. What has run:

  • Static. The file parses as YAML; both job bodies pass sh -n after the $$→$ unescape; the embedded generator passes ast.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 through ast.literal_eval; the Python-literal constraint from §2 is proven, not assumed.

  • The reconcile loop, against a fake bench that reproduces the two behaviours the job depends on (kwargs are a Python literal; output is un-indented json.dumps, nothing when falsy) and the doctype default enabled = 0. Eleven scenarios, all as intended:

    #scenarioresult
    1fresh install, one unknown doctype in the list3 rows, unknown skipped, rc=0
    2re-run unchanged3 rows, update path, rc=0
    3doctype removed from the liststale row reaped
    4a row disabled by handenabled back to 1
    5pickerUrl with a path prefixREFUSED, rc=1
    6pickerUrl with a bare trailing /accepted
    7pickerUrl emptyquiet no-op, rc=0
    8baked shim absentREFUSED naming IMAGE-OWNED, rc=1
    9write silently ignored by the servercaught by read-back, rc=1
    10unintegration beside a foreign Client Scriptonly ours removed, foreign row intact
    11unintegration with nothing to doremoved 0, rc=0

    Scenario 8 ran against the real /opt/shc/... path; the other ten substituted the bridge’s shim path, since /opt is not writable here.

  • Not run: go test ./tests/unit/catalog/ is red on this worktree before and after this file; TestNoPlugDeclaresAnUnreadKey aborts at plug_key_readers_test.go:249 because its catalogue walk expects apps/frappe while the tree has apps/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.