@powerhousedao/pieces-framework 6.2.3-dev.100

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,59 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Powerhouse Inc.
4
+
5
+ Applies to everything in this package outside upstream/ and test/upstream/
6
+ (src/, scripts/, test/, the build and package files).
7
+
8
+ Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ of this software and associated documentation files (the "Software"), to deal
10
+ in the Software without restriction, including without limitation the rights
11
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ copies of the Software, and to permit persons to whom the Software is
13
+ furnished to do so, subject to the following conditions:
14
+
15
+ The above copyright notice and this permission notice shall be included in all
16
+ copies or substantial portions of the Software.
17
+
18
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ SOFTWARE.
25
+
26
+ --------------------------------------------------------------------------------
27
+
28
+ The code under upstream/ and test/upstream/ is vendored from
29
+ https://github.com/activepieces/activepieces (packages/pieces/framework,
30
+ packages/pieces/common, packages/core/piece-types and packages/core/utils, none
31
+ of which lie under the "packages/ee/" carve-out) and stays under its original
32
+ license, reproduced verbatim below. The exact tag and commit are recorded in
33
+ upstream/MANIFEST.json.
34
+
35
+ Copyright (c) 2020-2024 Activepieces Inc.
36
+
37
+ Portions of this software are licensed as follows:
38
+
39
+ * All content that resides under the "packages/ee/" and "packages/server/api/src/app/ee" directory of this repository, if that directory exists, is licensed under the license defined in packages/ee/LICENSE
40
+ * All third party components incorporated into the Activepieces Inc Software are licensed under the original license provided by the owner of the applicable component.
41
+ * Content outside of the above mentioned directories or restrictions above is available under the "MIT Expat" license as defined below.
42
+
43
+ Permission is hereby granted, free of charge, to any person obtaining a copy
44
+ of this software and associated documentation files (the "Software"), to deal
45
+ in the Software without restriction, including without limitation the rights
46
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
47
+ copies of the Software, and to permit persons to whom the Software is
48
+ furnished to do so, subject to the following conditions:
49
+
50
+ The above copyright notice and this permission notice shall be included in all
51
+ copies or substantial portions of the Software.
52
+
53
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
54
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
55
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
56
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
57
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
58
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
59
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,372 @@
1
+ # @powerhousedao/pieces-framework
2
+
3
+ Powerhouse's published copy of the [Activepieces](https://www.activepieces.com)
4
+ piece framework, so a piece can be authored outside their monorepo.
5
+
6
+ It also adds `requireReactor`, which gives an action or trigger a
7
+ `ctx.reactor` for reading and writing Powerhouse documents. See
8
+ [Reactor access](#reactor-access-requirereactor-and-ctxreactor).
9
+
10
+ ## Why this package exists
11
+
12
+ Activepieces pieces are written against `@activepieces/pieces-framework` and
13
+ `@activepieces/pieces-common`. Since Activepieces v0.86.0 most pieces ship as
14
+ self-contained bundles with the framework inlined, and upstream stopped
15
+ publishing those two packages to npm. Anyone authoring a piece outside the
16
+ Activepieces monorepo has nothing to install.
17
+
18
+ "Most", not all: their bundler externalises what esbuild cannot trace, so a
19
+ piece can still declare a dependency — 21 of the 760 published ones do. A
20
+ reactor installs those before loading the piece, with lifecycle scripts
21
+ disabled, which is why one needing a postinstall or a native build will not
22
+ run there whatever version is pinned.
23
+
24
+ This package vendors the framework, `pieces-common` and the two core packages
25
+ they depend on from a pinned upstream tag (see [UPSTREAM.md](./UPSTREAM.md)),
26
+ publishes them as ESM under the Powerhouse release train, and adds the
27
+ Powerhouse types on top. The authoring API is upstream's, unchanged.
28
+
29
+ ```ts
30
+ import {
31
+ createAction,
32
+ createPiece,
33
+ PieceAuth,
34
+ Property,
35
+ } from "@powerhousedao/pieces-framework";
36
+ import { httpClient, HttpMethod } from "@powerhousedao/pieces-framework/common";
37
+ ```
38
+
39
+ ## Writing a piece for a reactor package
40
+
41
+ 1. **Start from a reactor package.** `ph init` gives you one; then add the
42
+ framework:
43
+
44
+ ```sh
45
+ pnpm add -D @powerhousedao/pieces-framework
46
+ ```
47
+
48
+ A dev dependency: `ph build` inlines the framework into each piece bundle.
49
+ The types need `@types/node`, which a `ph init` project already has.
50
+
51
+ 2. **Write the piece** in `pieces/<name>/index.ts` with `createPiece`,
52
+ `createAction`, `createTrigger` and `Property`, exactly as an Activepieces
53
+ piece:
54
+
55
+ ```ts
56
+ import {
57
+ createAction,
58
+ createPiece,
59
+ PieceAuth,
60
+ Property,
61
+ } from "@powerhousedao/pieces-framework";
62
+
63
+ const listInvoices = createAction({
64
+ auth: invoicesAuth,
65
+ name: "list_invoices",
66
+ displayName: "List invoices",
67
+ description: "Invoices in the billing system",
68
+ props: {
69
+ since: Property.ShortText({ displayName: "Since", required: false }),
70
+ },
71
+ async run(ctx) {
72
+ return clientFor(ctx.auth).listInvoices(ctx.propsValue.since);
73
+ },
74
+ });
75
+
76
+ export const invoices = createPiece({
77
+ displayName: "Invoices",
78
+ logoUrl: "https://example.com/invoices.png",
79
+ authors: ["acme"],
80
+ auth: invoicesAuth,
81
+ actions: [listInvoices],
82
+ triggers: [],
83
+ });
84
+ ```
85
+
86
+ A piece usually connects a reactor to something outside it, and a workflow
87
+ composes it with the reactor piece's document steps. An action that needs
88
+ documents itself declares `requireReactor`, below.
89
+
90
+ To give a connection a status and an account label in Connect, declare
91
+ `validate` and `getConnectionIdentifier` on the auth. Both are handed the
92
+ flat auth value (here the props themselves, not `{ type, props }`):
93
+
94
+ ```ts
95
+ const invoicesAuth = PieceAuth.CustomAuth({
96
+ displayName: "Invoices",
97
+ required: true,
98
+ props: {
99
+ base_url: Property.ShortText({
100
+ displayName: "Base URL",
101
+ required: true,
102
+ }),
103
+ token: PieceAuth.SecretText({ displayName: "Token", required: true }),
104
+ },
105
+ validate: async ({ auth }) => {
106
+ try {
107
+ await clientFor(auth).ping();
108
+ return { valid: true };
109
+ } catch (error) {
110
+ return { valid: false, error: String(error) };
111
+ }
112
+ },
113
+ getConnectionIdentifier: async ({ auth }) =>
114
+ (await clientFor(auth).me()).email,
115
+ });
116
+ ```
117
+
118
+ A reactor runs `validate` for the check's result and, when it passes,
119
+ `getConnectionIdentifier` for the account label. The label is best-effort:
120
+ returning `undefined` or throwing keeps the previous label and still passes
121
+ the check.
122
+
123
+ 3. **Register it.** List the piece in `pieces/index.ts` as a `PackagePiece`
124
+ and in the package manifest under `"pieces"`:
125
+
126
+ ```ts
127
+ import type { PackagePiece } from "@powerhousedao/pieces-framework";
128
+
129
+ export const pieces: PackagePiece[] = [
130
+ {
131
+ name: "@acme/pieces-invoices",
132
+ entry: "dist/node/pieces/invoices/index.mjs",
133
+ },
134
+ ];
135
+ ```
136
+
137
+ `entry` is the built module, relative to the package root: `ph build`
138
+ emits `pieces/<name>/index.ts` to `dist/node/pieces/<name>/index.mjs`.
139
+
140
+ 4. **Build.** `ph build` bundles each `pieces/<name>/index.ts` on its own
141
+ into `dist/node/pieces/<name>/index.mjs`, with everything but node
142
+ built-ins inlined — the framework, its dependencies and the shared set that
143
+ document models and subgraphs leave to the host — because a host runs a
144
+ piece in a forked worker with no `node_modules` beside it. It then loads
145
+ each built piece once, in a child process, and writes two files next to it:
146
+ `descriptor.json`, the piece's own `metadata()` in the Activepieces
147
+ `PieceMetadata` shape (display name, logo, auth, every action and trigger
148
+ with its properties), and a `package.json` that makes the directory a
149
+ complete bundle. The `pieces` list in `dist/powerhouse.manifest.json` gets
150
+ each piece's version, description, `bundle` and `descriptor` paths, so a
151
+ registry can offer the piece before anyone installs the package. A piece's
152
+ version is always the package's own: the build writes it, and refuses a
153
+ list entry that declares one.
154
+
155
+ A package that ships only pieces is still an ordinary reactor package: it
156
+ carries the same boilerplate as any other, including a root `index.ts`,
157
+ `document-models/index.ts`, `editors/index.ts` and `style.css`, even when
158
+ those are empty. `ph build` runs every step for it unchanged, so there is
159
+ no piece-only mode to know about. The host that runs pieces on a reactor
160
+ (the workflow runtime) reads the `pieces` list and imports each `entry`.
161
+
162
+ Bundling with esbuild to ESM instead of `ph build`? `form-data`, which
163
+ `./common` uses, is CommonJS, so pass
164
+ `--banner:js="import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);"`
165
+ or the bundle throws `Dynamic require of "util" is not supported` on import.
166
+
167
+ ## Reactor access: `requireReactor` and `ctx.reactor`
168
+
169
+ `createAction` and `createTrigger` from this package are upstream's, plus
170
+ `requireReactor: "read" | "write" | false`. The declaration types
171
+ `ctx.reactor` in every hook (`run` and `test`, and a trigger's other hooks):
172
+
173
+ ```ts
174
+ import { createAction, Property } from "@powerhousedao/pieces-framework";
175
+
176
+ export const archiveInvoice = createAction({
177
+ name: "archive-invoice",
178
+ displayName: "Archive invoice",
179
+ description: "Sets an invoice's status to ARCHIVED",
180
+ requireAuth: false,
181
+ requireReactor: "write",
182
+ props: {
183
+ invoiceId: Property.ShortText({ displayName: "Invoice", required: true }),
184
+ },
185
+ async run(ctx) {
186
+ const doc = await ctx.reactor.get(ctx.propsValue.invoiceId);
187
+ const invoice = await ctx.reactor.getDocumentModelModuleForDocument(doc);
188
+ const handle = await ctx.reactor.write.execute(doc.header.id, "main", [
189
+ invoice.actions.setStatus({ status: "ARCHIVED" }),
190
+ ]);
191
+ const { job } = await handle.readable;
192
+ if (job.result?.allApplied === false) throw new Error("Not archived");
193
+ const updated = await handle.document();
194
+ return { header: updated.header, state: updated.state };
195
+ },
196
+ });
197
+ ```
198
+
199
+ - `"read"` types `ctx.reactor` as `ReactorReadClient`, `"write"` as
200
+ `ReactorClient`. Both are `Pick`s of `IReactorClient`, with the client's own
201
+ signatures; `ReadMethods`, `WriteMethods` and `RefusedMethods` name the
202
+ methods. `false`, like no declaration, gives no `ctx.reactor`.
203
+ - `ReactorClient.write` is `ReactorWriteClient`, a `Pick` of the reactor's
204
+ `IReactorWriteClient`: `create`, `createEmpty`, `execute`, `deleteDocument`
205
+ (no cascade), and `drives.addFile` and `drives.addFolder`
206
+ (`WriteHalfMethods`, `DriveWriteHalfMethods`). Each answers once its job is
207
+ accepted with a handle: `written`, `readable` (a receipt whose
208
+ `job.result.actions` holds each action's outcome) and `document(view?)`. A
209
+ reducer error is on the receipt, not thrown.
210
+ - The facade's writes (`create`, `createEmpty`, `execute`, `executeAsync`,
211
+ `deleteDocument`, `drives.addFile`, `drives.addFolder`) are deprecated and
212
+ still served, so published pieces keep working. They return once applied and
213
+ throw `ReactorActionsFailedError` on a reducer error.
214
+ - Build actions with the model's action creators, such as `setName` from
215
+ `@powerhousedao/shared/document-model`, `addFile` from
216
+ `@powerhousedao/shared/document-drive`, or `module.actions.*` from
217
+ `getDocumentModelModuleForDocument`, and pass them to `write.execute`. It
218
+ refuses document lifecycle actions, and the client's convenience writes
219
+ (`rename`, relationships, upgrades, batches, other drive writes) are refused,
220
+ on the facade and on `write`. Read a drive's nodes with `drives.listNodes`.
221
+ - A write the run user may not make throws `ReactorAccessDeniedError` before
222
+ anything is submitted. Its message ends with
223
+ `denied action indexes: [0,2]`; `deniedActionIndexes(error)` reads them.
224
+ - `query({ subgraph, query, variables })` (`IndexQueryMethods`, on both
225
+ types) reads a read-model index the host serves as a GraphQL subgraph, by
226
+ the name the host registers it under, with the host's own permission rules
227
+ applied for the run user. It answers `{ data, errors? }` and takes queries
228
+ only; a mutation is refused. A host that serves no indexes refuses the
229
+ method by name.
230
+ - The types come from `@powerhousedao/reactor` and `@powerhousedao/shared`,
231
+ which are optional, type-only peer dependencies. The build emits no import
232
+ of either.
233
+ - `ph build` copies the declaration into `descriptor.json`.
234
+ `ph generate piece-action` and `ph generate piece-trigger` write
235
+ `requireReactor: false`, or the value of `--require-reactor read|write`.
236
+ - `createAction` also takes `defaultTimeoutSeconds` (positive) and
237
+ `defaultRetry` (`maxAttempts`, plus optional `backoff`,
238
+ `initialDelaySeconds`, `maxDelaySeconds` and `retryOn`), used for a step
239
+ that sets no timeout or retry of its own. The workflow's own default retry
240
+ wins over the action's. A `defaultRetry` without delays
241
+ backs off exponentially from 5s, capped at 300s. `ph generate piece-action`
242
+ writes them commented out, or set from `--default-timeout-seconds` and
243
+ `--default-max-attempts`.
244
+ - The host serves `ctx.reactor`. Each call acts as the workflow's run user,
245
+ within the step's reactor connection and deadline. A handle waits only for
246
+ its own step's jobs; a failed job rejects its stages with `JobFailedError`.
247
+ - Errors cross the worker boundary by `name` and `message`, so compare
248
+ `error.name` against the exported constants: `ReactorAccessDeniedError`,
249
+ `ReactorJobFailedError`, `ReactorActionsFailedError`,
250
+ `ReactorJobPendingError`, `ReactorRequestClosedError` and
251
+ `DocumentModelUnavailableError`.
252
+ - `Property.Dropdown`, `Property.MultiSelectDropdown` and
253
+ `Property.DynamicProperties` type their resolver's `ctx.reactor` as
254
+ `ReactorReadClient | undefined`. A declared block's resolvers read as the
255
+ person using the editor and never write; the client is undefined when the
256
+ block declares nothing.
257
+
258
+ The academy page
259
+ [Reactor access from pieces](../../apps/academy/docs/academy/02-Learn/09-workflows/03-reactor-access.mdx)
260
+ covers the run-time rules, reactor connections and the run user.
261
+
262
+ ## `./host`, for the host and not for piece authors
263
+
264
+ A host that _runs_ pieces needs more than the authoring API: stored prop values
265
+ arrive as strings from a form and have to be coerced to what the piece's
266
+ `props` declare, outbound requests have to be checked against the private
267
+ address space, and a thrown HTTP client error has to be turned into something a
268
+ user can read. Activepieces does all three in its engine; `./host` re-exports
269
+ that code so a Powerhouse host does not reimplement it.
270
+
271
+ ```ts
272
+ import {
273
+ formatPieceError,
274
+ processors,
275
+ propsProcessor,
276
+ ssrfIpClassifier,
277
+ } from "@powerhousedao/pieces-framework/host";
278
+ ```
279
+
280
+ From the engine, coercion of what an editor stored into what a piece's `props`
281
+ declare:
282
+
283
+ - `processors` — `PropertyType` → coercion function, for the eleven types that
284
+ need one, and `numberProcessor`, `checkboxProcessor`, `dateTimeProcessor`,
285
+ `fileProcessor`, `jsonProcessor`, `objectProcessor`, `textProcessor` and
286
+ `multiSelectProcessor` individually.
287
+ - `arrayZipperProcessor` — turns an object of parallel arrays into `ARRAY`
288
+ items; `ARRAY` has no entry in the map.
289
+ - `propsProcessor.applyProcessorsAndValidators` — a whole props map at once,
290
+ auth and nested `ARRAY`/`DYNAMIC` props included, returning the processed
291
+ input and per-key validation errors.
292
+ - `dynamicPropKeys` — escapes and restores `DYNAMIC` prop keys around a form
293
+ that treats `.` and `[` as path separators.
294
+ - `ProcessorFn`, and `PropertySettings` (ours, see
295
+ [UPSTREAM.md](./UPSTREAM.md)) for the stored `DYNAMIC` schema.
296
+
297
+ From `core-utils`, the two host jobs that are not coercion:
298
+
299
+ - `ssrfIpClassifier.isBlockedIp({ ip, allowList })` — blocks every non-unicast
300
+ range, with CIDR entries in the allow list.
301
+ - `formatPieceError` — lifts the API message out of an HTTP-shaped error,
302
+ strips an HTML error page down to its text and caps serialization depth;
303
+ with `tryParseFriendlyPieceError` and the `FriendlyPieceError` type.
304
+
305
+ Nothing here belongs in a piece: a piece is handed values that are already
306
+ coerced. `.` and `./common` are unchanged, and `test/surface.test.ts` holds them
307
+ that way.
308
+
309
+ The consumer is [`@powerhousedao/reactor-workflow`](../reactor-workflow), which
310
+ runs pieces on a reactor: its `context/normalize.ts` dispatches to `processors`,
311
+ its `worker/egress.ts` classifies with `ssrfIpClassifier`, and its worker runs a
312
+ thrown piece error through `formatPieceError` before redacting it.
313
+
314
+ The coercion half comes from `@activepieces/engine`, of which this package
315
+ vendors only the prop-coercion files, for the reasons in
316
+ [UPSTREAM.md](./UPSTREAM.md). `dayjs` (the DATE_TIME processor) and `ipaddr.js`
317
+ (the classifier) are runtime dependencies because `./host` reaches them.
318
+
319
+ ## `./block-type`, block identity and versions
320
+
321
+ A workflow names a block the way Activepieces does, with three fields:
322
+ `pieceName`, `pieceVersion` and `actionName` for a step, or `triggerName` for a
323
+ trigger. The engine's own blocks are a piece too, `@powerhousedao/piece-core`
324
+ (`CORE_PIECE_NAME` in `./workflow`). This module has no dependencies and is safe
325
+ in the browser, so the editor and the runtime share it.
326
+
327
+ A piece's version is the version of its package. The version is exact semver
328
+ 2.0: prereleases and build metadata are allowed, ranges and dist-tags are not.
329
+
330
+ - `isExactVersion(v)` says whether a version can be pinned.
331
+ - `blockKey({ pieceName, kind, name })` is the version-free identity as one
332
+ string, for map and cache keys.
333
+ - `compareVersions(a, b)` orders by semver precedence.
334
+ - `pickClosestVersion(requested, available)` returns `{ version, match }`,
335
+ picking the first rule that matches:
336
+ 1. The exact version (`exact`).
337
+ 2. The highest same-major version at or above the request (`compatible`).
338
+ 3. The highest same-major version below the request (`fallback`).
339
+ 4. The highest version of any major (`fallback`).
340
+
341
+ For `0.x`, same major means same minor.
342
+
343
+ ## Publishing the same piece to Activepieces
344
+
345
+ A piece written against this package is a plain Activepieces piece. To
346
+ contribute it upstream, scaffold one in the Activepieces monorepo with
347
+ `npm run cli pieces create`, copy your `src/` over its own, rewrite the import
348
+ specifiers (`@powerhousedao/pieces-framework` to
349
+ `@activepieces/pieces-framework`, `@powerhousedao/pieces-framework/common` to
350
+ `@activepieces/pieces-common`) and run `npm run build-piece <name>`.
351
+
352
+ ## Syncing upstream
353
+
354
+ ```sh
355
+ pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag d078d47750b53c13b837b2bec86b0402b4bff94f
356
+ ```
357
+
358
+ `scripts/sync-upstream.mts` is the only thing that writes `upstream/` and
359
+ `test/upstream/`. It fetches the tag, copies the four piece source trees plus a
360
+ named handful of engine files, rewrites
361
+ them to ESM with `.js` specifiers and type-only imports, formats them, applies
362
+ a short list of literal patches that fail loudly when upstream changes, and
363
+ records every file's upstream path and hash in `upstream/MANIFEST.json`.
364
+ Details in [UPSTREAM.md](./UPSTREAM.md).
365
+
366
+ ## License
367
+
368
+ MIT. The vendored Activepieces code keeps its original MIT license and
369
+ copyright, reproduced verbatim in [LICENSE](./LICENSE) alongside the Powerhouse
370
+ notice for everything else. The framework is inlined into every piece an
371
+ external developer builds, which is why this package is MIT rather than AGPL
372
+ like the rest of the Powerhouse monorepo.
package/UPSTREAM.md ADDED
@@ -0,0 +1,223 @@
1
+ # Upstream
2
+
3
+ `upstream/` and `test/upstream/` are generated from
4
+ [activepieces/activepieces](https://github.com/activepieces/activepieces).
5
+ Never edit them by hand; re-run the sync instead.
6
+
7
+ | | |
8
+ | --------- | ------------------------------------------ |
9
+ | Tag | none (`main`) |
10
+ | Commit | `d078d47750b53c13b837b2bec86b0402b4bff94f` |
11
+ | Committed | 2026-10-30 |
12
+
13
+ The same facts, plus the per-file upstream path and the SHA-256 of every
14
+ original file, live in `upstream/MANIFEST.json`; the package versions are in
15
+ `package.json` under `"upstream"`.
16
+
17
+ ## What is vendored
18
+
19
+ | Upstream package | Upstream path | Here |
20
+ | --------------------------------------- | ------------------------------- | ---------------------------- |
21
+ | `@activepieces/pieces-framework` 0.42.0 | `packages/pieces/framework/src` | `upstream/framework/` |
22
+ | `@activepieces/pieces-common` 0.15.1 | `packages/pieces/common/src` | `upstream/common/` |
23
+ | `@activepieces/core-piece-types` 0.12.3 | `packages/core/piece-types/src` | `upstream/core-piece-types/` |
24
+ | `@activepieces/core-utils` 0.11.0 | `packages/core/utils/src` | `upstream/core-utils/` |
25
+ | `@activepieces/engine` 0.7.0 | `packages/server/engine/src` | `upstream/engine/` |
26
+
27
+ The first four are vendored whole. The engine is not: `PACKAGES` gives it an
28
+ explicit `files` list, and the sync fails if any listed path disappears
29
+ upstream. Only the prop-coercion corner is taken — `lib/variables/processors/*`,
30
+ `lib/variables/props-processor.ts` and `lib/helper/dynamic-prop-keys.ts` — which
31
+ is what `./host` re-exports. Everything else in that package reaches for the
32
+ flow executor, the isolated-vm sandbox or the platform API: the trigger helper,
33
+ the piece executor and loader, and `lib/helper/error-handling.ts`, whose
34
+ retry/continue-on-failure logic takes `EngineConstants` and
35
+ `FlowExecutorContext` and so would drag the whole handler tree in.
36
+ `lib/variables/property-path.ts` is left out too: `props-processor.ts` does not
37
+ import it, and it would add a `jsep` dependency.
38
+
39
+ Each package's own vitest suites (`*.spec.ts`, `*.test.ts` under `src/`, and
40
+ `test/`) go to `test/upstream/<package>/` and run with `pnpm test`.
41
+
42
+ Left out: `mime-db-min.cjs` (upstream's bundler alias that keeps `mime-db`,
43
+ pulled in through `form-data`, out of piece bundles; aliasing is the piece
44
+ build's job, so `ph build` may adopt it later) and upstream's unused `ai` and
45
+ `semver` dependencies.
46
+ Of the engine's own tests only those that exercise vendored code come along:
47
+ `test/variables/{props-validator,file-processor,dynamic-prop-keys}.test.ts`,
48
+ `test/helper/polling-helper.test.ts` and
49
+ `test/http/formdata-multipart-claim-verify.test.ts` (which guards the patched
50
+ `fetch-http-client.ts`). The rest need `@activepieces/shared`,
51
+ `props-resolver` or `FlowExecutorContext`.
52
+
53
+ `@activepieces/shared` (8k lines of platform entities) is not vendored. The four
54
+ piece packages never import it; the engine files do, so the codemod re-homes
55
+ each symbol they use — `AUTHENTICATION_PROPERTY_NAME` and `AppConnectionValue`
56
+ to `upstream/core-piece-types/`, which really defines them, and `PropertySettings`
57
+ and `PropertyExecutionType` to `src/host/shared-shim.ts`, a Powerhouse-owned
58
+ declaration of the minimal shapes `props-processor.ts` and its tests read. An
59
+ unmapped symbol fails the sync.
60
+
61
+ `deepmerge-ts` is a devDependency only: `core-utils` imports it in
62
+ `deepMergeAndCast`, which the framework barrel never re-exports, so the source
63
+ typechecks against it and the build tree-shakes it away. `test/dist.test.ts`
64
+ fails if a sync makes it reachable; that is the moment to move it to
65
+ `dependencies`. `ipaddr.js` and `dayjs` are runtime dependencies because `./host`
66
+ does reach them, through `ssrfIpClassifier` and the DATE_TIME processor.
67
+
68
+ ## How to sync
69
+
70
+ ```sh
71
+ pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag <tag or commit SHA>
72
+ # or, from a checkout you already have at that tag or commit:
73
+ pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag <tag> --from ../activepieces
74
+ ```
75
+
76
+ Without `--from` the script sparse-clones the tag (or fetches the commit) into a temp dir. Then run the
77
+ gates (`tsc`, `lint`, `test`, `build`) and commit the result together with the
78
+ `UPSTREAM.md` table above. The script is idempotent: running it twice yields no
79
+ diff.
80
+
81
+ ## What the codemod changes
82
+
83
+ Upstream is CommonJS with extensionless imports; this package is ESM under
84
+ `NodeNext` with `verbatimModuleSyntax`. For every copied `.ts` file the script:
85
+
86
+ 1. Rewrites bare `@activepieces/{pieces-framework,pieces-common,core-piece-types,core-utils}`
87
+ imports to relative paths into `upstream/`.
88
+ 2. Adds `.js` (or `/index.js`) to relative specifiers, resolved against the
89
+ real files.
90
+ 3. Prefixes node builtins with `node:`, and adds the extension Node's ESM
91
+ resolver will not infer for a subpath of a dependency with no `"exports"`
92
+ map (`dayjs/plugin/utc` becomes `dayjs/plugin/utc.js`).
93
+ 4. Prepends a two-line header naming the upstream path and the tag.
94
+ 5. Marks type-only imports and re-exports with ts-morph
95
+ (`scripts/sync-upstream-type-only.mts`, a port of typescript-eslint's
96
+ `consistent-type-imports` and `consistent-type-exports` fixes) so they
97
+ satisfy `verbatimModuleSyntax` and `isolatedModules`, then formats the tree
98
+ with the repo's prettier config.
99
+ 6. Splits an `@activepieces/shared` import across the modules that really own
100
+ each symbol, per `SHARED_SYMBOL_HOMES`.
101
+ 7. Applies the literal patches listed in `PATCHES` in
102
+ `scripts/sync-upstream.mts`. Each must match exactly the expected number of
103
+ times or the sync fails, so a change upstream cannot go unnoticed.
104
+
105
+ Current patches:
106
+
107
+ - `upstream/common/lib/http/core/fetch-http-client.ts`: cast a buffered
108
+ form-data body to `BodyInit` (`@types/node` 25 no longer accepts
109
+ `Buffer<ArrayBufferLike>` there), and replace a `@ts-expect-error` whose
110
+ target line prettier moves with an explicit cast on `Readable.fromWeb`.
111
+ - `upstream/common/lib/http/core/fetch-http-client.ts`: drop the unconditional
112
+ `process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"` at the top of `sendRequest`.
113
+ That flag is process-wide, so it disabled certificate verification for every
114
+ HTTPS request in the host for as long as the process ran, not just the
115
+ current one. Upstream's own bug (activepieces/activepieces@main still has
116
+ it); no design here relies on it.
117
+ - `upstream/common/lib/http/core/fetch-http-client.ts`: stop `console.error`-ing
118
+ the `HttpError` built for a failed request. `HttpError`'s message embeds the
119
+ raw outgoing request body, so this was writing piece secrets (API keys,
120
+ tokens, form fields) to host-level logs on every failed call. Upstream's own
121
+ bug too; callers already get the same detail back via `toFailsafeOutput`.
122
+ - `upstream/common/lib/stream/index.ts`: guard `readChunks` against a
123
+ non-positive `chunkSize`. `pendingLength >= chunkSize` is permanently true
124
+ for `chunkSize <= 0`, so the drain loop never yields control back to the
125
+ outer `for await`, hanging the generator forever. Unreachable today (nothing
126
+ calls it yet) but it is public framework API.
127
+ - `upstream/common/lib/helpers/index.ts`: in `createCustomApiCallAction`, stop
128
+ injecting `authValue` into headers whenever `authLocation` is merely
129
+ non-nil. `authLocation` defaults to `"headers"` and is never actually nil at
130
+ that point, so `authLocation === "headers" || !isNil(authLocation)` always
131
+ held — query-param credentials were duplicated into the request headers.
132
+ - `upstream/framework/lib/property/input/array-property.ts`: add
133
+ `JsonProperty` and `ColorProperty` to the runtime `ArraySubProps` union (and
134
+ import them as values). The exported `ArraySubProps<R>` type and
135
+ `Property.Array` both already allow Json/Color sub-properties; the runtime
136
+ schema rejected them.
137
+ - `upstream/framework/lib/property/input/array-property.ts`: make
138
+ `ArrayProperty`'s `properties` field `z.optional(...)`. The exported
139
+ `ArrayProperty<R>` type already marks it optional, and
140
+ `piecePropertiesUtils.buildSchema` already handles an absent value; the
141
+ runtime schema required it.
142
+ - `upstream/framework/lib/property/input/index.ts`: add `CustomProperty` to
143
+ the runtime `InputProperty` union (and import it as a value).
144
+ `Property.Custom` builds exactly that shape, and it's part of the exported
145
+ `InputProperty` type, but the runtime schema rejected it.
146
+ - `upstream/framework/lib/property/authentication/custom-auth-prop.ts`: add
147
+ `SecretTextProperty`, `MarkDownProperty` and `StaticMultiSelectDropdownProperty`
148
+ to the runtime `CustomAuthProps` union (and import them as values). All
149
+ three are part of the exported `CustomAuthProps` type; the runtime schema
150
+ was narrower.
151
+ - `upstream/framework/lib/property/input/markdown-property.ts`: add an
152
+ optional `variant` field to the runtime `MarkDownProperty` schema.
153
+ `Property.MarkDown` always writes one and the exported type declares it,
154
+ but the schema had no such key, so zod silently stripped
155
+ `WARNING`/`TIP`/`BORDERLESS` variants on parse.
156
+ - `upstream/framework/lib/property/input/file-property.ts`: add an optional
157
+ `path` to `ApStreamingFile`, the absolute path of a streaming FILE staged on
158
+ local disk. reactor-workflow sets it so a piece can read the file in place
159
+ (DuckDB, for one) instead of copying the body out first.
160
+ - `upstream/framework/lib/trigger/trigger.ts`: give `createTrigger`'s switch a
161
+ `default` that throws, naming the trigger and its `type`. The switch had none,
162
+ so a missing or misspelt strategy returned `undefined`, and the piece failed
163
+ later wherever that trigger was first read. TypeScript already rejects it;
164
+ this covers code that bypasses the types.
165
+ - `upstream/framework/index.ts` and `upstream/framework/lib/property/index.ts`:
166
+ re-export `SeekPage`, `McpAuthConfig` and `InputProperty` as values instead
167
+ of `export type`. Each is a zod schema merged with a type; rolldown-plugin-dts
168
+ drops the `type` modifier when it bundles `dist/index.d.ts`, so upstream's
169
+ type-only re-export let `import { SeekPage }` typecheck and then fail at link
170
+ time. The runtime gains three exports upstream's lacks; `test/dist.test.ts`
171
+ holds the d.ts to the runtime.
172
+ - `upstream/engine/lib/variables/props-processor.ts`: export
173
+ `validateProperty`, the validator half of `applyProcessorsAndValidators`.
174
+ A host that coerces values with its own processors first (reactor-workflow
175
+ hydrates FILE props itself) validates the result with it.
176
+ - `test/upstream/framework/test/connection-identifier-flag.test.ts`: pass
177
+ `authors: []` to `createPiece` (upstream does not typecheck its tests).
178
+ - `test/upstream/engine/test/variables/dynamic-prop-keys.test.ts`: pass
179
+ `auth: undefined` to `Property.DynamicProperties`, which requires it.
180
+ - `test/upstream/core-utils/test/ai-provider-health.test.ts`: make the outcome
181
+ reporter return `void` instead of `Array.prototype.push`'s number (three
182
+ sites).
183
+ - `test/upstream/engine/test/variables/file-processor.test.ts`: cast the
184
+ processor's `unknown` result to `ApStreamingFile` instead of annotating the
185
+ binding (five sites).
186
+ - `test/upstream/engine/test/variables/props-validator.test.ts`: pass
187
+ `auth: undefined` to `Property.Dropdown` and `Property.MultiSelectDropdown`,
188
+ which require it.
189
+
190
+ The vendored trees are excluded from the root ESLint run: their lint stance is
191
+ upstream's, and the codemod already applies this repo's formatting.
192
+
193
+ ## Conformance suite for reactor-workflow
194
+
195
+ The same sync also generates
196
+ [`../reactor-workflow/test/upstream/`](../reactor-workflow/test/upstream):
197
+ Activepieces engine tests that run against our engine instead of vendored code.
198
+ It lives in this script rather than a second one so that one run, from one
199
+ checkout, regenerates both trees under one codemod and one patch contract.
200
+
201
+ `CONFORMANCE` in `scripts/sync-upstream.mts` lists each upstream test and its
202
+ target, optionally cut down to literal `excerpt` segments. For each file the
203
+ sync:
204
+
205
+ 1. Rewrites `@activepieces/pieces-framework` and `@activepieces/pieces-common`
206
+ to our published `@powerhousedao/pieces-framework` entries.
207
+ 2. Rewrites every other upstream import through `IMPORT_REDIRECTS` to an adapter
208
+ in `../reactor-workflow/test/upstream-adapters/`, which exposes the upstream
209
+ API (`createContextStore`, `createConnectionResolver`, `ssrfGuard`,
210
+ `propsProcessor`, the `@activepieces/shared` symbols) over our code. An
211
+ import with no redirect fails the sync.
212
+ 3. Adds the header, formats, and applies `CONFORMANCE_PATCHES`, which carry the
213
+ same `count` and `why` as `PATCHES`.
214
+ 4. Marks each `CONFORMANCE_SKIPS` case `it.skip` and each `KNOWN_DIVERGENCES`
215
+ case `it.fails`, with a comment giving the reason and, for a divergence, the
216
+ issue or README item that fixes it; a deliberate divergence names none. A
217
+ name that no longer matches upstream fails the sync. When a fix lands, its
218
+ `it.fails` starts failing: drop the entry and re-sync.
219
+ 5. Writes `test/upstream/MANIFEST.json` there, with the upstream path and
220
+ SHA-256 of each original and the lists of divergences and skips.
221
+
222
+ Nothing is taken from `packages/ee/` or `packages/server/api/src/app/ee`, which
223
+ are not MIT.