|
| 1 | +--- |
| 2 | +name: add-selector |
| 3 | +description: Add or update a Sim dynamic selector using the shared manifest, server attachment, and selectors.execute path. Use for provider-backed, internal, or local option lists referenced by block, trigger, or connector selectorKey fields. |
| 4 | +argument-hint: <selector-key> |
| 5 | +--- |
| 6 | + |
| 7 | +# Add Selector |
| 8 | + |
| 9 | +Dynamic selectors expose option metadata while a workflow or connector is being configured. Every |
| 10 | +remote selector executes through the authorized `selectors.execute` application operation; the |
| 11 | +browser never resolves credentials or calls a provider directly. |
| 12 | + |
| 13 | +## Read the shared boundary |
| 14 | + |
| 15 | +Before editing, read: |
| 16 | + |
| 17 | +- `apps/sim/lib/selectors/types.ts` |
| 18 | +- `apps/sim/lib/selectors/manifest.ts` |
| 19 | +- `apps/sim/lib/selectors/context.ts` |
| 20 | +- `apps/sim/lib/selectors/server/types.ts` |
| 21 | +- `apps/sim/lib/selectors/server/registry.ts` |
| 22 | +- `apps/sim/hooks/queries/selectors.ts` |
| 23 | + |
| 24 | +Then read the nearest existing selector attachment and the block, trigger, or connector declaration |
| 25 | +that will consume the key. |
| 26 | + |
| 27 | +## Classify the selector |
| 28 | + |
| 29 | +- `provider-server`: contacts an external provider or uses provider credentials. |
| 30 | +- `internal-server`: reads protected Sim data through an existing authorized application use case. |
| 31 | +- `local`: pure browser-safe data with no protected data, credentials, references, or network I/O. |
| 32 | + |
| 33 | +Add every key to the browser-safe manifest in `lib/selectors/manifest.ts`. `SelectorKey` derives from |
| 34 | +that manifest; do not maintain a second union. Manifest entries contain data only: allowed context, |
| 35 | +readiness, scope kinds, list/search/detail capabilities, and stale time. Do not import provider SDKs, |
| 36 | +credentials, server helpers, or attachment functions into the manifest. |
| 37 | + |
| 38 | +## Build context from active values |
| 39 | + |
| 40 | +Declare `dependsOn` on the consuming sub-block or connector field. The shared context builder sends |
| 41 | +only declared, active dependencies: |
| 42 | + |
| 43 | +- Canonical basic/advanced pairs contribute the active value under their canonical key. |
| 44 | +- Action and trigger modes contribute only fields active on that surface. |
| 45 | +- Exact environment references such as `{{GMAIL_CREDENTIAL_ID}}` remain unresolved in the browser. |
| 46 | +- Runtime block-output references are not selector context. |
| 47 | +- Embedded environment interpolation such as `https://{{HOST}}/path` is unsupported. |
| 48 | +- `impersonateUserEmail` is the one explicit compatibility hint projected when the manifest allows |
| 49 | + it, even when it is absent from `dependsOn`. |
| 50 | + |
| 51 | +Add a new `SelectorContextKey` only when the value is a real, reusable selector dependency. Allow it |
| 52 | +explicitly on each relevant manifest entry. Never send a full block or connector configuration. |
| 53 | + |
| 54 | +## Add the server attachment |
| 55 | + |
| 56 | +For `provider-server`, add the service's attachment map under |
| 57 | +`apps/sim/lib/selectors/server/providers/` and include it in the exhaustive server registry. For |
| 58 | +`internal-server`, add the attachment in `apps/sim/lib/selectors/server/internal.ts`. Local keys use |
| 59 | +the exhaustive browser-safe registry in `apps/sim/lib/selectors/client/local.ts` and never enter the |
| 60 | +server registry. A provider attachment declares: |
| 61 | + |
| 62 | +- For stored credentials, a credential policy with the exact context field and trusted |
| 63 | + `serviceIds`. Raw-connection selectors instead validate the connection material projected from |
| 64 | + their allowed context and bind it to a deliberate destination policy. |
| 65 | +- Destination policy: `fixed`, `credential-bound`, or `user-controlled`. |
| 66 | +- A list/detail adapter that explicitly projects `id`, `label`, and allowlisted scalar `meta`. |
| 67 | + |
| 68 | +Stored credentials must pass actor-use, workspace, and provider/service binding checks. Do not trust |
| 69 | +a provider, service, operation kind, origin, or module name supplied by the browser. |
| 70 | + |
| 71 | +Choose the destination policy deliberately: |
| 72 | + |
| 73 | +- `fixed`: provider origin is code-defined. |
| 74 | +- `credential-bound`: origin/account/site comes from, or is verified against, the authorized |
| 75 | + credential. |
| 76 | +- `user-controlled`: the user selects the destination. Hidden use-only authentication requires an |
| 77 | + explicit security policy; do not combine it with an arbitrary destination by default. |
| 78 | + |
| 79 | +Reuse or extract a server-only provider listing primitive. If an existing provider route has |
| 80 | +non-selector callers, keep the route as a thin caller of that primitive. If it is selector-only, |
| 81 | +move the logic and remove the obsolete route and contract. Never import a route handler or make an |
| 82 | +internal HTTP request from an attachment. |
| 83 | + |
| 84 | +The attachment must return normalized selector results only. It must never deliberately or |
| 85 | +wholesale echo selector context, and hidden/server-only resolved material, credential IDs, tokens, |
| 86 | +and authentication secrets must never cross the response boundary. Browser-known literals and |
| 87 | +viewable personal/shared values are not automatically server-only secrets, but they may appear in |
| 88 | +an option only when the adapter intentionally projects them as provider resource metadata. Let the |
| 89 | +shared executor own scope authorization, exact-reference resolution, credential authorization, |
| 90 | +error projection, and output sanitization; adapters must pass and preserve the executor's abort |
| 91 | +signal during provider work. |
| 92 | + |
| 93 | +## Wire the UI declaration |
| 94 | + |
| 95 | +Point the block, trigger, or connector field at `selectorKey` and declare its `dependsOn` fields. |
| 96 | +Keep connector selector/manual canonical pairs and fork reconfiguration behavior intact. Static |
| 97 | +`options` stay local and need no selector. |
| 98 | + |
| 99 | +Do not add: |
| 100 | + |
| 101 | +- A module under `hooks/selectors/providers` or any client provider fetcher. |
| 102 | +- A provider-specific React Query key. |
| 103 | +- A selector-specific OAuth-token request. |
| 104 | +- A selector-only API route when the provider primitive can be called directly. |
| 105 | + |
| 106 | +All server selectors use the shared POST contract and React Query facade. Query identities must stay |
| 107 | +opaque and must not include context values, references, credential IDs, secrets, or their hashes. |
| 108 | +Selector code must not add context, token, or result caches. The sole existing cache exception is |
| 109 | +authorized client-credential resolution after authorization and provider binding: it may reuse the |
| 110 | +credential service's TTL-governed, lazily pruned process-local token cache. This exception requires |
| 111 | +explicit security-owner acceptance; do not broaden it or describe it as hard-bounded. |
| 112 | + |
| 113 | +## Focused validation |
| 114 | + |
| 115 | +Follow nearby Vitest and route-test style. Do not add an authorization matrix for every ordinary |
| 116 | +provider attachment; the shared executor tests own shared security behavior. |
| 117 | + |
| 118 | +Add a focused adapter test when behavior is special, such as pagination, nontrivial destination |
| 119 | +binding, provider-specific projection, or a raw-connection policy. For an ordinary fixed-origin OAuth |
| 120 | +list, manifest/registry exhaustiveness plus an existing provider primitive test is usually enough. |
| 121 | + |
| 122 | +Run the smallest relevant set, then: |
| 123 | + |
| 124 | +```bash |
| 125 | +bunx vitest run <focused selector tests> |
| 126 | +bun run --cwd apps/sim type-check |
| 127 | +bun run check:fork-dependent-coverage |
| 128 | +bun run check:client-boundary |
| 129 | +git diff --check |
| 130 | +``` |
| 131 | + |
| 132 | +Confirm there is no browser-side provider call, every server key has one attachment, and every |
| 133 | +returned option is explicitly projected. |
0 commit comments