@powerhousedao/pieces-framework 6.2.3-dev.11

package/LICENSE

@@ -0,0 +1,59 @@
+MIT License
+
+Copyright (c) 2026 Powerhouse Inc.
+
+Applies to everything in this package outside upstream/ and test/upstream/
+(src/, scripts/, test/, the build and package files).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+The code under upstream/ and test/upstream/ is vendored from
+https://github.com/activepieces/activepieces (packages/pieces/framework,
+packages/pieces/common, packages/core/piece-types and packages/core/utils, none
+of which lie under the "packages/ee/" carve-out) and stays under its original
+license, reproduced verbatim below. The exact tag and commit are recorded in
+upstream/MANIFEST.json.
+
+Copyright (c) 2020-2024 Activepieces Inc.
+
+Portions of this software are licensed as follows:
+
+* 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
+* All third party components incorporated into the Activepieces Inc Software are licensed under the original license provided by the owner of the applicable component.
+* Content outside of the above mentioned directories or restrictions above is available under the "MIT Expat" license as defined below.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @powerhousedao/pieces-framework
+
+Powerhouse's published copy of the [Activepieces](https://www.activepieces.com)
+piece framework, plus the one thing a piece running on a Powerhouse reactor
+gets that no other host serves: `ctx.reactor`.
+
+## Why this package exists
+
+Activepieces pieces are written against `@activepieces/pieces-framework` and
+`@activepieces/pieces-common`. Since Activepieces v0.86.0 pieces ship as
+self-contained bundles with the framework inlined, and upstream stopped
+publishing those two packages to npm. Anyone authoring a piece outside the
+Activepieces monorepo has nothing to install.
+
+This package vendors the framework, `pieces-common` and the two core packages
+they depend on from a pinned upstream tag (see [UPSTREAM.md](./UPSTREAM.md)),
+publishes them as ESM under the Powerhouse release train, and adds the
+Powerhouse types on top. The authoring API is upstream's, unchanged.
+
+```ts
+import {
+  createAction,
+  createPiece,
+  Property,
+  reactorOf,
+} from "@powerhousedao/pieces-framework";
+import { httpClient, HttpMethod } from "@powerhousedao/pieces-framework/common";
+```
+
+## Writing a piece for a reactor package
+
+1. **Start from a reactor package.** `ph init` gives you one; then add the
+   framework:
+
+   ```sh
+   pnpm add @powerhousedao/pieces-framework
+   ```
+
+   The types need `@types/node`, which a `ph init` project already has.
+
+2. **Write the piece** in `pieces/<name>/index.ts` with `createPiece`,
+   `createAction`, `createTrigger` and `Property`, exactly as an Activepieces
+   piece. The reactor the piece runs inside is on every context; read it with
+   `reactorOf(ctx)`:
+
+   ```ts
+   import {
+     createAction,
+     createPiece,
+     PieceAuth,
+     Property,
+     reactorOf,
+   } from "@powerhousedao/pieces-framework";
+
+   const listInvoices = createAction({
+     name: "list_invoices",
+     displayName: "List invoices",
+     description: "Invoices on this reactor",
+     props: {
+       parentId: Property.ShortText({ displayName: "Drive", required: false }),
+     },
+     async run(ctx) {
+       return reactorOf(ctx).find({
+         documentType: "powerhouse/invoice",
+         parentId: ctx.propsValue.parentId,
+       });
+     },
+   });
+
+   export const invoices = createPiece({
+     displayName: "Invoices",
+     logoUrl: "https://example.com/invoices.png",
+     authors: ["acme"],
+     auth: PieceAuth.None(),
+     actions: [listInvoices],
+     triggers: [],
+   });
+   ```
+
+   `ReactorService` offers `models()`, `model(type)`, `get`, `find`, `create`
+   and `execute`. The typed contexts are exported too:
+   `PowerhouseActionContext`, `PowerhousePropertyContext`,
+   `PowerhouseTriggerHookContext` and the generic `WithReactor<C>`.
+
+3. **Register it.** List the piece in `pieces/index.ts` as a `PackagePiece`
+   and in the package manifest under `"pieces"`:
+
+   ```ts
+   import type { PackagePiece } from "@powerhousedao/pieces-framework";
+
+   export const pieces: PackagePiece[] = [
+     {
+       name: "@acme/pieces-invoices",
+       version: "1.0.0",
+       entry: "dist/node/pieces/invoices/index.mjs",
+     },
+   ];
+   ```
+
+   `entry` is the built module, relative to the package root: `ph build`
+   emits `pieces/<name>/index.ts` to `dist/node/pieces/<name>/index.mjs`.
+
+4. **Build.** `ph build` inlines the framework into each piece bundle under
+   `dist/node/pieces`, so a host loads a self-contained module. The host that
+   runs pieces on a reactor (the workflow runtime, arriving separately) reads
+   the `pieces` list, imports each `entry` and serves `ctx.reactor`.
+
+   Bundling with esbuild to ESM instead of `ph build`? `form-data`, which
+   `./common` uses, is CommonJS, so pass
+   `--banner:js="import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);"`
+   or the bundle throws `Dynamic require of "util" is not supported` on import.
+
+Outside a Powerhouse reactor, `reactorOf(ctx)` throws an error that names
+`ctx.reactor`, so a piece that ends up on another host fails legibly.
+
+## `./host`, for the host and not for piece authors
+
+A host that _runs_ pieces needs more than the authoring API: stored prop values
+arrive as strings from a form and have to be coerced to what the piece's
+`props` declare, outbound requests have to be checked against the private
+address space, and a thrown HTTP client error has to be turned into something a
+user can read. Activepieces does all three in its engine; `./host` re-exports
+that code so a Powerhouse host does not reimplement it.
+
+```ts
+import {
+  formatPieceError,
+  processors,
+  propsProcessor,
+  ssrfIpClassifier,
+} from "@powerhousedao/pieces-framework/host";
+```
+
+From the engine, coercion of what an editor stored into what a piece's `props`
+declare:
+
+- `processors` — `PropertyType` → coercion function, for the eleven types that
+  need one, and `numberProcessor`, `checkboxProcessor`, `dateTimeProcessor`,
+  `fileProcessor`, `jsonProcessor`, `objectProcessor`, `textProcessor` and
+  `multiSelectProcessor` individually.
+- `arrayZipperProcessor` — turns an object of parallel arrays into `ARRAY`
+  items; `ARRAY` has no entry in the map.
+- `propsProcessor.applyProcessorsAndValidators` — a whole props map at once,
+  auth and nested `ARRAY`/`DYNAMIC` props included, returning the processed
+  input and per-key validation errors.
+- `dynamicPropKeys` — escapes and restores `DYNAMIC` prop keys around a form
+  that treats `.` and `[` as path separators.
+- `ProcessorFn`, and `PropertySettings` (ours, see
+  [UPSTREAM.md](./UPSTREAM.md)) for the stored `DYNAMIC` schema.
+
+From `core-utils`, the two host jobs that are not coercion:
+
+- `ssrfIpClassifier.isBlockedIp({ ip, allowList })` — blocks every non-unicast
+  range, with CIDR entries in the allow list.
+- `formatPieceError` — lifts the API message out of an HTTP-shaped error,
+  strips an HTML error page down to its text and caps serialization depth;
+  with `tryParseFriendlyPieceError` and the `FriendlyPieceError` type.
+
+Nothing here belongs in a piece: a piece is handed values that are already
+coerced. `.` and `./common` are unchanged, and `test/surface.test.ts` holds them
+that way.
+
+The consumer is [`@powerhousedao/reactor-workflow`](../reactor-workflow), which
+runs pieces on a reactor: its `context/normalize.ts` dispatches to `processors`,
+its `worker/egress.ts` classifies with `ssrfIpClassifier`, and its worker runs a
+thrown piece error through `formatPieceError` before redacting it.
+
+The coercion half comes from `@activepieces/engine`, of which this package
+vendors only the prop-coercion files, for the reasons in
+[UPSTREAM.md](./UPSTREAM.md). `dayjs` (the DATE_TIME processor) and `ipaddr.js`
+(the classifier) are runtime dependencies because `./host` reaches them.
+
+## Publishing the same piece to Activepieces
+
+A piece that does not use `ctx.reactor` is a plain Activepieces piece. To
+contribute it upstream, scaffold one in the Activepieces monorepo with
+`npm run cli pieces create`, copy your `src/` over its own, rewrite the import
+specifiers (`@powerhousedao/pieces-framework` to
+`@activepieces/pieces-framework`, `@powerhousedao/pieces-framework/common` to
+`@activepieces/pieces-common`) and run `npm run build-piece <name>`.
+
+## Syncing upstream
+
+```sh
+pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag 0.91.0
+```
+
+`scripts/sync-upstream.mts` is the only thing that writes `upstream/` and
+`test/upstream/`. It fetches the tag, copies the four piece source trees plus a
+named handful of engine files, rewrites
+them to ESM with `.js` specifiers and type-only imports, formats them, applies
+a short list of literal patches that fail loudly when upstream changes, and
+records every file's upstream path and hash in `upstream/MANIFEST.json`.
+Details in [UPSTREAM.md](./UPSTREAM.md).
+
+## License
+
+MIT. The vendored Activepieces code keeps its original MIT license and
+copyright, reproduced verbatim in [LICENSE](./LICENSE) alongside the Powerhouse
+notice for everything else. The framework is inlined into every piece an
+external developer builds, which is why this package is MIT rather than AGPL
+like the rest of the Powerhouse monorepo.

package/UPSTREAM.md

@@ -0,0 +1,172 @@
+# Upstream
+
+`upstream/` and `test/upstream/` are generated from
+[activepieces/activepieces](https://github.com/activepieces/activepieces).
+Never edit them by hand; re-run the sync instead.
+
+|           |                                            |
+| --------- | ------------------------------------------ |
+| Tag       | `0.91.0`                                   |
+| Commit    | `da4410d1bf6212054e55805a98d566ff1b9310b2` |
+| Committed | 2026-09-14                                 |
+
+The same facts, plus the per-file upstream path and the SHA-256 of every
+original file, live in `upstream/MANIFEST.json`; the package versions are in
+`package.json` under `"upstream"`.
+
+## What is vendored
+
+| Upstream package                        | Upstream path                   | Here                         |
+| --------------------------------------- | ------------------------------- | ---------------------------- |
+| `@activepieces/pieces-framework` 0.39.0 | `packages/pieces/framework/src` | `upstream/framework/`        |
+| `@activepieces/pieces-common` 0.14.0    | `packages/pieces/common/src`    | `upstream/common/`           |
+| `@activepieces/core-piece-types` 0.11.1 | `packages/core/piece-types/src` | `upstream/core-piece-types/` |
+| `@activepieces/core-utils` 0.6.2        | `packages/core/utils/src`       | `upstream/core-utils/`       |
+| `@activepieces/engine` 0.7.0            | `packages/server/engine/src`    | `upstream/engine/`           |
+
+The first four are vendored whole. The engine is not: `PACKAGES` gives it an
+explicit `files` list, and the sync fails if any listed path disappears
+upstream. Only the prop-coercion corner is taken — `lib/variables/processors/*`,
+`lib/variables/props-processor.ts` and `lib/helper/dynamic-prop-keys.ts` — which
+is what `./host` re-exports. Everything else in that package reaches for the
+flow executor, the isolated-vm sandbox or the platform API: the trigger helper,
+the piece executor and loader, and `lib/helper/error-handling.ts`, whose
+retry/continue-on-failure logic takes `EngineConstants` and
+`FlowExecutorContext` and so would drag the whole handler tree in.
+`lib/variables/property-path.ts` is left out too: `props-processor.ts` does not
+import it, and it would add a `jsep` dependency.
+
+Each package's own vitest suites (`*.spec.ts`, `*.test.ts` under `src/`, and
+`test/`) go to `test/upstream/<package>/` and run with `pnpm test`.
+
+Left out: `mime-db-min.cjs` (upstream's bundler alias that keeps `mime-db`,
+pulled in through `form-data`, out of piece bundles; aliasing is the piece
+build's job, so `ph build` may adopt it later) and upstream's unused `ai` and
+`semver` dependencies.
+Of the engine's own tests only `test/variables/props-validator.test.ts` and
+`test/variables/file-processor.test.ts` come along: the rest need
+`@activepieces/shared`, `props-resolver` or `FlowExecutorContext`.
+
+`@activepieces/shared` (8k lines of platform entities) is not vendored. The four
+piece packages never import it; the engine files do, so the codemod re-homes
+each symbol they use — `AUTHENTICATION_PROPERTY_NAME` and `AppConnectionValue`
+to `upstream/core-piece-types/`, which really defines them, and `PropertySettings`
+to `src/host/shared-shim.ts`, a Powerhouse-owned declaration of the minimal
+shape `props-processor.ts` reads. An unmapped symbol fails the sync.
+
+`deepmerge-ts` is a devDependency only: `core-utils` imports it in
+`deepMergeAndCast`, which the framework barrel never re-exports, so the source
+typechecks against it and the build tree-shakes it away. `test/dist.test.ts`
+fails if a sync makes it reachable; that is the moment to move it to
+`dependencies`. `ipaddr.js` and `dayjs` are runtime dependencies because `./host`
+does reach them, through `ssrfIpClassifier` and the DATE_TIME processor.
+
+## How to sync
+
+```sh
+pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag <tag>
+# or, from a checkout you already have at that tag:
+pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag <tag> --from ../activepieces
+```
+
+Without `--from` the script sparse-clones the tag into a temp dir. Then run the
+gates (`tsc`, `lint`, `test`, `build`) and commit the result together with the
+`UPSTREAM.md` table above. The script is idempotent: running it twice yields no
+diff.
+
+## What the codemod changes
+
+Upstream is CommonJS with extensionless imports; this package is ESM under
+`NodeNext` with `verbatimModuleSyntax`. For every copied `.ts` file the script:
+
+1. Rewrites bare `@activepieces/{pieces-framework,pieces-common,core-piece-types,core-utils}`
+   imports to relative paths into `upstream/`.
+2. Adds `.js` (or `/index.js`) to relative specifiers, resolved against the
+   real files.
+3. Prefixes node builtins with `node:`, and adds the extension Node's ESM
+   resolver will not infer for a subpath of a dependency with no `"exports"`
+   map (`dayjs/plugin/utc` becomes `dayjs/plugin/utc.js`).
+4. Prepends a two-line header naming the upstream path and the tag.
+5. Runs `eslint --fix` with `scripts/sync-upstream.eslint.config.mjs`
+   (`consistent-type-imports`, `consistent-type-exports`, prettier) so
+   type-only imports and re-exports satisfy `verbatimModuleSyntax` and
+   `isolatedModules`. Unused-directive reporting is off there, so upstream's
+   `eslint-disable` comments survive even though their rules do not run.
+6. Splits an `@activepieces/shared` import across the modules that really own
+   each symbol, per `SHARED_SYMBOL_HOMES`.
+7. Applies the literal patches listed in `PATCHES` in
+   `scripts/sync-upstream.mts`. Each must match exactly the expected number of
+   times or the sync fails, so a change upstream cannot go unnoticed.
+
+Current patches:
+
+- `upstream/common/lib/http/core/fetch-http-client.ts`: cast a buffered
+  form-data body to `BodyInit` (`@types/node` 25 no longer accepts
+  `Buffer<ArrayBufferLike>` there), and replace a `@ts-expect-error` whose
+  target line prettier moves with an explicit cast on `Readable.fromWeb`.
+- `upstream/common/lib/http/core/fetch-http-client.ts`: drop the unconditional
+  `process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"` at the top of `sendRequest`.
+  That flag is process-wide, so it disabled certificate verification for every
+  HTTPS request in the host for as long as the process ran, not just the
+  current one. Upstream's own bug (activepieces/activepieces@main still has
+  it); no design here relies on it.
+- `upstream/common/lib/http/core/fetch-http-client.ts`: stop `console.error`-ing
+  the `HttpError` built for a failed request. `HttpError`'s message embeds the
+  raw outgoing request body, so this was writing piece secrets (API keys,
+  tokens, form fields) to host-level logs on every failed call. Upstream's own
+  bug too; callers already get the same detail back via `toFailsafeOutput`.
+- `upstream/common/lib/stream/index.ts`: guard `readChunks` against a
+  non-positive `chunkSize`. `pendingLength >= chunkSize` is permanently true
+  for `chunkSize <= 0`, so the drain loop never yields control back to the
+  outer `for await`, hanging the generator forever. Unreachable today (nothing
+  calls it yet) but it is public framework API.
+- `upstream/common/lib/helpers/index.ts`: in `createCustomApiCallAction`, stop
+  injecting `authValue` into headers whenever `authLocation` is merely
+  non-nil. `authLocation` defaults to `"headers"` and is never actually nil at
+  that point, so `authLocation === "headers" || !isNil(authLocation)` always
+  held — query-param credentials were duplicated into the request headers.
+- `upstream/framework/lib/property/input/array-property.ts`: add
+  `JsonProperty` and `ColorProperty` to the runtime `ArraySubProps` union (and
+  import them as values). The exported `ArraySubProps<R>` type and
+  `Property.Array` both already allow Json/Color sub-properties; the runtime
+  schema rejected them.
+- `upstream/framework/lib/property/input/array-property.ts`: make
+  `ArrayProperty`'s `properties` field `z.optional(...)`. The exported
+  `ArrayProperty<R>` type already marks it optional, and
+  `piecePropertiesUtils.buildSchema` already handles an absent value; the
+  runtime schema required it.
+- `upstream/framework/lib/property/input/index.ts`: add `CustomProperty` to
+  the runtime `InputProperty` union (and import it as a value).
+  `Property.Custom` builds exactly that shape, and it's part of the exported
+  `InputProperty` type, but the runtime schema rejected it.
+- `upstream/framework/lib/property/authentication/custom-auth-prop.ts`: add
+  `SecretTextProperty`, `MarkDownProperty` and `StaticMultiSelectDropdownProperty`
+  to the runtime `CustomAuthProps` union (and import them as values). All
+  three are part of the exported `CustomAuthProps` type; the runtime schema
+  was narrower.
+- `upstream/framework/lib/property/input/markdown-property.ts`: add an
+  optional `variant` field to the runtime `MarkDownProperty` schema.
+  `Property.MarkDown` always writes one and the exported type declares it,
+  but the schema had no such key, so zod silently stripped
+  `WARNING`/`TIP`/`BORDERLESS` variants on parse.
+- `upstream/framework/index.ts` and `upstream/framework/lib/property/index.ts`:
+  re-export `SeekPage`, `McpAuthConfig` and `InputProperty` as values instead
+  of `export type`. Each is a zod schema merged with a type; rolldown-plugin-dts
+  drops the `type` modifier when it bundles `dist/index.d.ts`, so upstream's
+  type-only re-export let `import { SeekPage }` typecheck and then fail at link
+  time. The runtime gains three exports upstream's lacks; `test/dist.test.ts`
+  holds the d.ts to the runtime.
+- `test/upstream/framework/test/connection-identifier-flag.test.ts`: pass
+  `authors: []` to `createPiece` (upstream does not typecheck its tests).
+- `test/upstream/core-utils/test/ai-provider-health.test.ts`: make the outcome
+  reporter return `void` instead of `Array.prototype.push`'s number (three
+  sites).
+- `test/upstream/engine/test/variables/file-processor.test.ts`: cast the
+  processor's `unknown` result to `ApStreamingFile` instead of annotating the
+  binding (five sites).
+- `test/upstream/engine/test/variables/props-validator.test.ts`: pass
+  `auth: undefined` to `Property.Dropdown` and `Property.MultiSelectDropdown`,
+  which require it.
+
+The vendored trees are excluded from the root ESLint run: their lint stance is
+upstream's, and the codemod already applies this repo's formatting.