@flowrunner/cli 0.1.8 → 0.1.9-dev.2

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.
Files changed (73) hide show
  1. package/README.md +8 -8
  2. package/ai-docs/instructions/service-code-format/01-service-structure.md +4 -3
  3. package/ai-docs/instructions/service-code-format/02-zod-types.md +8 -0
  4. package/ai-docs/instructions/service-code-format/03-parameters.md +166 -10
  5. package/ai-docs/instructions/service-code-format/04-http-requests.md +19 -15
  6. package/ai-docs/instructions/service-code-format/05-dictionaries.md +14 -0
  7. package/ai-docs/instructions/service-code-format/06-oauth2.md +1 -5
  8. package/ai-docs/instructions/service-code-format/07-actions.md +18 -13
  9. package/ai-docs/instructions/service-code-format/11-output-model.md +42 -6
  10. package/ai-docs/instructions/service-code-format/12-service-readme.md +1 -1
  11. package/ai-docs/instructions/service-code-format/14-reference-service.md +5 -4
  12. package/ai-docs/instructions/service-code-format/15-unit-tests.md +2 -1
  13. package/ai-docs/instructions/service-code-format/16-gotchas.md +31 -1
  14. package/ai-docs/instructions/service-code-format/17-client-certificates.md +5 -3
  15. package/ai-docs/instructions/service-code-format/README.md +1 -1
  16. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
  17. package/dist/cli.js +285 -42
  18. package/dist/cli.js.map +3 -3
  19. package/dist/index.js +284 -41
  20. package/dist/index.js.map +3 -3
  21. package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  22. package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  23. package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  24. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  25. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  26. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  27. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  28. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  29. package/dist/types/flow-extension-runner/src/v2/types.d.ts +21 -9
  30. package/dist/types/shared/src/constants/activity-log.d.ts +1496 -0
  31. package/dist/types/shared/src/constants/docs.d.ts +2 -0
  32. package/dist/types/shared/src/constants/notification-types.d.ts +11 -5
  33. package/dist/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  34. package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  35. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  36. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  37. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  38. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  39. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  40. package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  41. package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  42. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  43. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  44. package/package.json +1 -1
  45. package/runtime/index.js +267 -41
  46. package/runtime/index.js.map +3 -3
  47. package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  48. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  49. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  50. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  51. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  52. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  53. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  54. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  55. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +21 -9
  56. package/runtime/types/shared/src/constants/activity-log.d.ts +1496 -0
  57. package/runtime/types/shared/src/constants/docs.d.ts +2 -0
  58. package/runtime/types/shared/src/constants/notification-types.d.ts +11 -5
  59. package/runtime/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  60. package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  61. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  62. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  63. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  64. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  65. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  66. package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  67. package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  68. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  69. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  70. package/templates/blank/files/src/index.js +1 -1
  71. package/templates/demo-todo-list/files/src/index.js +7 -7
  72. package/templates/qa-test/files/README.md +23 -8
  73. package/templates/qa-test/files/src/index.js +367 -38
@@ -50,10 +50,12 @@ initContext: ({ config }) => ({
50
50
  clientKey : config.clientKey,
51
51
  }),
52
52
 
53
- apiRequest: async ({ url, method = 'get', body, query, context }) =>
54
- new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
53
+ apiRequest: async ({ url, method = 'get', body, query, context }) => {
54
+ return new Flowrunner.Request(`${ context.apiUrl }${ url }`, method)
55
55
  .cert({ cert: context.clientCert, key: context.clientKey })
56
- .query(query),
56
+ .query(query)
57
+ .send(body)
58
+ }
57
59
  ```
58
60
 
59
61
  See [01-service-structure.md](01-service-structure.md) for `configItems` and `initContext`.
@@ -58,7 +58,7 @@ conditional groups that apply, together.
58
58
  |---|----------|--------|
59
59
  | 1 | [01-service-structure.md](01-service-structure.md) | `Flowrunner.createExtension(props)`: id/name/logo/colors, `usesFileStorage`, `configItems`, `initContext`, `apiRequest`, `helpers`; folder layout |
60
60
  | 2 | [02-zod-types.md](02-zod-types.md) | zod types & plugins — widget derived from type; `.label`/`.describe`/`.example`/`.optional`/`.default`/`.shared`/`.dictionary`/`.map` |
61
- | 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — and `dynamicParams` (runtime-generated fields) |
61
+ | 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — `.dynamicProps()` (an object param's inner fields, loaded at design time) and `dynamicParams` (extra top-level params, loaded the same way) |
62
62
  | 4 | [04-http-requests.md](04-http-requests.md) | the shared `apiRequest` helper, and the `Flowrunner.Request` client under it — sending model, methods, query, headers, bodies, multipart, responses, `ResponseError` |
63
63
  | 5 | [05-dictionaries.md](05-dictionaries.md) | `ext.dictionary(props)` — dynamic param options; `label` (→ `operationName`, always set it), `criteria` → auto `dependsOn`, optional `result` sample |
64
64
  | 6 | [07-actions.md](07-actions.md) | `ext.addAction(props)`, the shared `execute` context bag, and input validation |
@@ -62,7 +62,7 @@ Requirements, not preferences. A suite that breaks one is wrong even when it is
62
62
  `global.Flowrunner`, never reach for an internal. Behaviour unreachable through a method call is not the
63
63
  service's contract and not yours to test.
64
64
  2. **Group by `registerAs`.** Top-level groups are exactly `Actions`, `Dictionaries`, `OAuth`,
65
- `Polling Triggers`, `RealTime Triggers`, `DynamicResults`, `DynamicParams`. A method's group comes from
65
+ `Polling Triggers`, `RealTime Triggers`, `DynamicResults`, `DynamicParams`, `DynamicProps`. A method's group comes from
66
66
  its registration, never its subject matter — `sendPhoto` and `getChannel` are both `Actions`. Never
67
67
  invent a group (`Media`, `Messaging`…). **SYSTEM trigger methods are the one kind with no group and no
68
68
  `describe` of their own** — see rule 10.
package/dist/cli.js CHANGED
@@ -4185,7 +4185,7 @@ var require_package = __commonJS({
4185
4185
  "package.json"(exports2, module2) {
4186
4186
  module2.exports = {
4187
4187
  name: "@flowrunner/cli",
4188
- version: "0.1.8",
4188
+ version: "0.1.9-dev.2",
4189
4189
  publishConfig: {
4190
4190
  access: "public"
4191
4191
  },
@@ -5397,6 +5397,7 @@ var InvalidDictionaryOutputScheme = class extends FlowExtensionError {
5397
5397
  // ../../flow-extension-runner/src/v2/loaders/loader-owner.ts
5398
5398
  var sampleResultLoaderName = (ownerId) => `${ownerId}_SampleResultLoader`;
5399
5399
  var dynamicParamsLoaderName = (ownerId) => `${ownerId}_DynamicParams`;
5400
+ var dynamicPropsLoaderName = (ownerId, field) => `${ownerId}_${field}_DynamicProps`;
5400
5401
 
5401
5402
  // ../../flow-extension-runner/src/v2/params/schema/assert-object-schema.ts
5402
5403
  var WRAPPERS = /* @__PURE__ */ new Set(["optional", "nullable", "nullish", "default", "prefault"]);
@@ -5440,8 +5441,9 @@ function assertObjectSchema(scheme, source) {
5440
5441
  const isReturn = slot.endsWith("()");
5441
5442
  const subject = source.itemId ? `${kind} "${source.itemId}": ` : "";
5442
5443
  const received = describe(scheme);
5444
+ const expected = slot.endsWith(".execute()") ? "a z.object({ \u2026 }) or a shape of zod fields" : "a z.object({ \u2026 })";
5443
5445
  throw new InvalidSchemaError(
5444
- `[flow-extension:${source.serviceId}] ${subject}\`${slot}\` ${isReturn ? "must return" : "must be"} a z.object({ \u2026 }) \u2014 received ${received}${hint(scheme, slot, isReturn)}`,
5446
+ `[flow-extension:${source.serviceId}] ${subject}\`${slot}\` ${isReturn ? "must return" : "must be"} ${expected} \u2014 received ${received}${hint(scheme, slot, isReturn)}`,
5445
5447
  { serviceId: source.serviceId, kind, itemId: source.itemId, slot, received }
5446
5448
  );
5447
5449
  }
@@ -5664,12 +5666,82 @@ function refuseType(source, path23, type) {
5664
5666
  type ?? "unknown"
5665
5667
  );
5666
5668
  }
5667
- function assertField(schema, source, path23, seen) {
5669
+ var DYNAMIC_PROPS_FIX = "Declare it as `z.looseObject({ \u2026 }).dynamicProps({ dependsOn, execute })`, or `z.array(z.looseObject({ \u2026 })).dynamicProps(\u2026)` for a list of objects.";
5670
+ function isLooseObject(schema) {
5671
+ if (!schema) {
5672
+ return false;
5673
+ }
5674
+ const ins = inspect(schema);
5675
+ const catchall = ins.core?._zod?.def?.catchall;
5676
+ return ins.resolvedType === "object" && catchall?._zod?.def?.type === "unknown";
5677
+ }
5678
+ function isDynamicPropsSlot(source, topLevel) {
5679
+ return topLevel && source.kind === "action" && source.slot === "params";
5680
+ }
5681
+ function assertDynamicProps(schema, name, siblings, source, path23) {
5682
+ const ins = inspect(schema);
5683
+ const spec = ins.meta.frDynamicProps;
5684
+ if (!spec || !("execute" in spec)) {
5685
+ return;
5686
+ }
5687
+ if (typeof spec.execute !== "function") {
5688
+ refuse(
5689
+ `${subjectOf(source, path23)}: \`.dynamicProps()\` needs an \`execute\` function that returns the loaded fields.`,
5690
+ source,
5691
+ path23,
5692
+ typeof spec.execute
5693
+ );
5694
+ }
5695
+ if (spec.dependsOn !== void 0 && (!Array.isArray(spec.dependsOn) || spec.dependsOn.some((item) => typeof item !== "string"))) {
5696
+ refuse(
5697
+ `${subjectOf(source, path23)}: \`.dynamicProps()\` \`dependsOn\` must be an array of param names.`,
5698
+ source,
5699
+ path23,
5700
+ "dependsOn"
5701
+ );
5702
+ }
5703
+ for (const dependency of spec.dependsOn ?? []) {
5704
+ if (dependency === name || !siblings.includes(dependency)) {
5705
+ refuse(
5706
+ `${subjectOf(source, path23)}: \`.dynamicProps()\` depends on "${dependency}", which is not another param of this action. Name its sibling params: ${siblings.filter((sibling) => sibling !== name).join(", ") || "none"}.`,
5707
+ source,
5708
+ path23,
5709
+ dependency
5710
+ );
5711
+ }
5712
+ }
5713
+ if (ins.meta.frDictionary) {
5714
+ refuse(
5715
+ `${subjectOf(source, path23)} declares both \`.dynamicProps()\` and \`.dictionary()\`. A dictionary offers values for one field; dynamic props load the fields inside an object \u2014 use one or the other.`,
5716
+ source,
5717
+ path23,
5718
+ "dictionary"
5719
+ );
5720
+ }
5721
+ const element = ins.resolvedType === "array" ? ins.core?._zod?.def?.element : void 0;
5722
+ if (!isLooseObject(schema) && !isLooseObject(element)) {
5723
+ refuse(
5724
+ `${subjectOf(source, path23)}: \`.dynamicProps()\` needs a loose object \u2014 the loaded fields are not declared, so a plain \`z.object()\` would strip them. ${DYNAMIC_PROPS_FIX}`,
5725
+ source,
5726
+ path23,
5727
+ ins.resolvedType ?? "unknown"
5728
+ );
5729
+ }
5730
+ }
5731
+ function assertField(schema, source, path23, seen, topLevel = false) {
5668
5732
  if (!schema || seen.has(schema)) {
5669
5733
  return;
5670
5734
  }
5671
5735
  seen.add(schema);
5672
5736
  const ins = inspect(schema);
5737
+ if (ins.meta.frDynamicProps && !isDynamicPropsSlot(source, topLevel)) {
5738
+ refuse(
5739
+ `${subjectOf(source, path23)} uses \`.dynamicProps()\`, which is supported on top-level action params only. For a list of objects, put it on the array rather than on its element.`,
5740
+ source,
5741
+ path23,
5742
+ "dynamicProps"
5743
+ );
5744
+ }
5673
5745
  if (ins.resolvedType === "catch") {
5674
5746
  refuseCatch(source, path23);
5675
5747
  }
@@ -5698,8 +5770,13 @@ function assertSupportedSchema(scheme, source) {
5698
5770
  }
5699
5771
  const slot = source.slot ?? "schema";
5700
5772
  const seen = /* @__PURE__ */ new Set();
5701
- for (const [name, field] of shapeEntries(scheme)) {
5702
- assertField(field, source, `${slot}.${name}`, seen);
5773
+ const fields = shapeEntries(scheme);
5774
+ const names = fields.map(([name]) => name);
5775
+ for (const [name, field] of fields) {
5776
+ assertField(field, source, `${slot}.${name}`, seen, true);
5777
+ if (isDynamicPropsSlot(source, true)) {
5778
+ assertDynamicProps(field, name, names, source, `${slot}.${name}`);
5779
+ }
5703
5780
  }
5704
5781
  }
5705
5782
 
@@ -6521,6 +6598,9 @@ function extendPrototype() {
6521
6598
  proto.labels = function labels(byValue) {
6522
6599
  return this.meta({ frLabels: byValue });
6523
6600
  };
6601
+ proto.dynamicProps = function dynamicProps(spec) {
6602
+ return this.meta({ frDynamicProps: spec });
6603
+ };
6524
6604
  proto.map = function map() {
6525
6605
  throw new Error(
6526
6606
  "`.map({ Label: value })` has been replaced by `.labels({ value: 'Label' })` \u2014 declare the VALUES in the enum and the labels here, so a flow element stores the value and renaming a label is safe. e.g. z.enum(['asc', 'desc']).labels({ asc: 'Ascending', desc: 'Descending' })"
@@ -6741,10 +6821,36 @@ function unwrap(schema) {
6741
6821
  }
6742
6822
  return result;
6743
6823
  }
6744
- function encodeMeta(meta) {
6745
- const encoded = toJsonValue2(meta);
6824
+ function isDynamicPropsSpec(value) {
6825
+ return !!value && typeof value === "object" && typeof value.execute === "function";
6826
+ }
6827
+ function hasFunction(value, depth = 0) {
6828
+ if (typeof value === "function") {
6829
+ return true;
6830
+ }
6831
+ if (!value || typeof value !== "object" || depth > MAX_UNWRAP_DEPTH) {
6832
+ return false;
6833
+ }
6834
+ return Object.values(value).some((inner) => hasFunction(inner, depth + 1));
6835
+ }
6836
+ function encodeMeta(meta, field, loaderId) {
6837
+ let source = meta;
6838
+ if (isDynamicPropsSpec(meta.frDynamicProps)) {
6839
+ if (!loaderId) {
6840
+ throw new Error(`Cannot encode "${field}": its \`.dynamicProps()\` has no loader method to publish.`);
6841
+ }
6842
+ source = { ...meta, frDynamicProps: { id: loaderId, dependsOn: meta.frDynamicProps.dependsOn ?? [] } };
6843
+ }
6844
+ if (hasFunction(source)) {
6845
+ throw new Error(`Cannot encode "${field}": its metadata holds a function, which has no wire form.`);
6846
+ }
6847
+ const encoded = toJsonValue2(source);
6746
6848
  return Object.keys(encoded).length ? encoded : void 0;
6747
6849
  }
6850
+ function isLoose(core) {
6851
+ const catchall = core?._zod?.def?.catchall;
6852
+ return catchall?._zod?.def?.type === "unknown";
6853
+ }
6748
6854
  function encodeValues(core, type) {
6749
6855
  if (type === "enum") {
6750
6856
  const entries = core?._zod?.def?.entries ?? {};
@@ -6756,7 +6862,7 @@ function encodeValues(core, type) {
6756
6862
  }
6757
6863
  return void 0;
6758
6864
  }
6759
- function encodeField(name, schema, seen = /* @__PURE__ */ new Set()) {
6865
+ function encodeField(name, schema, seen = /* @__PURE__ */ new Set(), loaderId) {
6760
6866
  if (seen.has(schema)) {
6761
6867
  return { name, type: "unknown", unsupported: ["recursion"] };
6762
6868
  }
@@ -6769,7 +6875,7 @@ function encodeField(name, schema, seen = /* @__PURE__ */ new Set()) {
6769
6875
  const isUnion = !!ins.branches;
6770
6876
  const format = isUnion ? void 0 : core?._zod?.def?.format;
6771
6877
  const { checks, unsupported: checkIssues } = isUnion ? { checks: [], unsupported: [] } : encodeChecks(core);
6772
- const meta = encodeMeta(ins.meta);
6878
+ const meta = encodeMeta(ins.meta, name, loaderId);
6773
6879
  const message = isUnion ? void 0 : messageOf(core?._zod?.def ?? {});
6774
6880
  const values = encodeValues(core, type);
6775
6881
  const problems = [...unsupported, ...checkIssues];
@@ -6787,6 +6893,7 @@ function encodeField(name, schema, seen = /* @__PURE__ */ new Set()) {
6787
6893
  ...values?.length ? { values } : {},
6788
6894
  ...meta ? { meta } : {},
6789
6895
  ...message ? { message } : {},
6896
+ ...type === "object" && isLoose(core) ? { loose: true } : {},
6790
6897
  ...type === "object" ? { properties: shapeEntries(core).map(([key, inner]) => encodeField(key, inner, seen)) } : {},
6791
6898
  ...type === "array" ? { element: encodeField("", core?._zod?.def?.element, seen) } : {},
6792
6899
  ...type === "record" ? { value: encodeField("", core?._zod?.def?.valueType, seen) } : {},
@@ -6796,14 +6903,14 @@ function encodeField(name, schema, seen = /* @__PURE__ */ new Set()) {
6796
6903
  seen.delete(schema);
6797
6904
  return encoded;
6798
6905
  }
6799
- function encodeParams(scheme) {
6906
+ function encodeParams(scheme, options = {}) {
6800
6907
  const schema = scheme;
6801
6908
  if (!schema?._zod) {
6802
6909
  return null;
6803
6910
  }
6804
6911
  return {
6805
6912
  v: SCHEMA_JSON_VERSION,
6806
- fields: shapeEntries(schema).map(([name, field]) => encodeField(name, field))
6913
+ fields: shapeEntries(schema).map(([name, field]) => encodeField(name, field, /* @__PURE__ */ new Set(), options.loaderIdOf?.(name)))
6807
6914
  };
6808
6915
  }
6809
6916
 
@@ -7119,11 +7226,50 @@ var ActionMethod = class extends ExtensionMethod {
7119
7226
  this.props = props;
7120
7227
  this.params = MethodParams.of(props.params, { serviceId: extension.id, kind: "action", itemId: props.id, slot: "params" });
7121
7228
  this.result = ResultSpec.from(props.result);
7122
- this.dynamicParamsCriteria = MethodParams.of(props.dynamicParams?.criteria, {
7123
- serviceId: extension.id,
7124
- kind: "action",
7125
- itemId: props.id,
7126
- slot: "dynamicParams.criteria"
7229
+ this.dynamicParams = props.dynamicParams ? this.#checkDynamicParams(props.dynamicParams) : void 0;
7230
+ }
7231
+ /**
7232
+ * `dynamicParams` takes the same `{ dependsOn, execute }` as `.dynamicProps()`. The old
7233
+ * `{ criteria, resolve }` shape is refused by name, so a service written against it fails at load with the
7234
+ * fix rather than publishing a loader that never runs.
7235
+ */
7236
+ #checkDynamicParams(def) {
7237
+ const source = { serviceId: this.extension.id, kind: "action", itemId: this.props.id, slot: "dynamicParams" };
7238
+ const fail3 = (message, received) => {
7239
+ throw new InvalidSchemaError(`[flow-extension:${this.extension.id}] action "${this.props.id}": ${message}`, { ...source, received });
7240
+ };
7241
+ const legacy = def;
7242
+ if (legacy.resolve !== void 0 || legacy.criteria !== void 0) {
7243
+ fail3(
7244
+ "`dynamicParams: { criteria, resolve }` has been replaced by `dynamicParams: { dependsOn, execute }` \u2014 name the params it depends on and return the loaded fields from `execute`. e.g. dynamicParams: { dependsOn: ['tableName'], execute: async ({ criteria }) => ({ name: z.string() }) }",
7245
+ "criteria/resolve"
7246
+ );
7247
+ }
7248
+ if (typeof def.execute !== "function") {
7249
+ fail3("`dynamicParams` needs an `execute` function that returns the loaded params.", typeof def.execute);
7250
+ }
7251
+ if (def.dependsOn !== void 0 && (!Array.isArray(def.dependsOn) || def.dependsOn.some((item) => typeof item !== "string"))) {
7252
+ fail3("`dynamicParams.dependsOn` must be an array of param names.", def.dependsOn);
7253
+ }
7254
+ const declared = this.params.keys();
7255
+ for (const dependency of def.dependsOn ?? []) {
7256
+ if (!declared.includes(dependency)) {
7257
+ fail3(
7258
+ `\`dynamicParams\` depends on "${dependency}", which the action does not declare in \`params\`. Declared: ${declared.join(", ") || "none"}.`,
7259
+ dependency
7260
+ );
7261
+ }
7262
+ }
7263
+ return def;
7264
+ }
7265
+ /**
7266
+ * The top-level params declared with `.dynamicProps()`, and the def each one carries. Placement and shape
7267
+ * were checked when `params` was built (see ../params/schema/assert-supported-schema.ts).
7268
+ */
7269
+ dynamicPropsFields() {
7270
+ return this.params.fields().flatMap(([name, schema]) => {
7271
+ const def = inspect(schema).meta.frDynamicProps;
7272
+ return def && "execute" in def ? [[name, def]] : [];
7127
7273
  });
7128
7274
  }
7129
7275
  get id() {
@@ -7149,8 +7295,9 @@ var ActionMethod = class extends ExtensionMethod {
7149
7295
  * Normalize, coerce and validate against the declared `params` — the same pipeline every other declared
7150
7296
  * slot uses, so an author expresses optionality in the schema and nowhere else.
7151
7297
  *
7152
- * An action with `dynamicParams` carries the input's undeclared keys through, since its runtime-generated
7153
- * top-level fields are not in the static schema.
7298
+ * An action with `dynamicParams` carries the input's undeclared keys through, since its loaded top-level
7299
+ * fields are not in the static schema. A `.dynamicProps()` field needs nothing here: it is a loose object,
7300
+ * which keeps the loaded keys inside it.
7154
7301
  */
7155
7302
  validate(methodData) {
7156
7303
  return this.params.normalize(
@@ -7162,22 +7309,22 @@ var ActionMethod = class extends ExtensionMethod {
7162
7309
  execute(params, ctx) {
7163
7310
  return this.props.execute(ctx.bagWith({ params }));
7164
7311
  }
7165
- // Resolve the extra top-level param fields this action generates at runtime (see 03-parameters.md).
7166
- resolveDynamicParams(bag) {
7167
- return this.props.dynamicParams.resolve(bag);
7168
- }
7169
7312
  // ── output model ───────────────────────────────────────────────────────────
7170
7313
  toModel() {
7171
7314
  const [ownStart, ownEnd] = this.props.appearanceColors ?? [];
7172
7315
  const [colorStart, colorEnd] = this.extension.appearanceColors;
7316
+ const args = toArgs(this.params);
7173
7317
  const metaInfo = {
7174
- args: toArgs(this.params),
7318
+ args,
7175
7319
  ...this.result.toMetaInfo(this.id, this.params)
7176
7320
  };
7177
- if (this.hasDynamicParams()) {
7321
+ for (const [name, def] of this.dynamicPropsFields()) {
7322
+ args[name] = { ...args[name], schemaLoader: dynamicPropsLoaderName(this.id, name), dependsOn: def.dependsOn ?? [] };
7323
+ }
7324
+ if (this.dynamicParams) {
7178
7325
  metaInfo.dynamicParams = {
7179
7326
  methodName: dynamicParamsLoaderName(this.id),
7180
- dependsOn: this.dynamicParamsCriteria.keys()
7327
+ dependsOn: this.dynamicParams.dependsOn ?? []
7181
7328
  };
7182
7329
  }
7183
7330
  return {
@@ -7192,7 +7339,7 @@ var ActionMethod = class extends ExtensionMethod {
7192
7339
  returnType: this.result.returnType,
7193
7340
  queryParams: [],
7194
7341
  bodyParams: toBodyParams(this.params),
7195
- paramsSchema: encodeParams(this.params.scheme),
7342
+ paramsSchema: encodeParams(this.params.scheme, { loaderIdOf: (name) => dynamicPropsLoaderName(this.id, name) }),
7196
7343
  metaInfo
7197
7344
  };
7198
7345
  }
@@ -7454,7 +7601,11 @@ var LoaderMethod = class extends ExtensionMethod {
7454
7601
  validate(methodData) {
7455
7602
  const input = this.input(methodData);
7456
7603
  const payload = input.parseField("payload", LoaderPayloadSchema);
7457
- return this.criteria.normalize(payload.criteria, input.invalidCriteria(), { carryUnknown: true });
7604
+ return this.criteria.normalize(payload.criteria, input.invalidCriteria(), { carryUnknown: this.carryUnknown });
7605
+ }
7606
+ // Whether the criteria's undeclared keys ride through to the handler.
7607
+ get carryUnknown() {
7608
+ return true;
7458
7609
  }
7459
7610
  // Internal (SYSTEM-like): no icon, no colours, no sample. Its params are left opaque in the model — it is
7460
7611
  // invoked with `{ criteria }` at runtime, not through a rendered form.
@@ -7486,7 +7637,9 @@ var SampleResultLoaderMethod = class extends LoaderMethod {
7486
7637
  get returnType() {
7487
7638
  return "OBJECT";
7488
7639
  }
7489
- // The sample varies with ANY param of the owner, so all of them are its criteria.
7640
+ // The sample varies with ANY param of the owner, so all of them are its criteria. Undeclared keys ride
7641
+ // through too: the node's other params come along, and the owner's `result` fn may read fields its
7642
+ // `dynamicParams` loaded.
7490
7643
  get criteria() {
7491
7644
  return this.owner.params;
7492
7645
  }
@@ -7494,31 +7647,101 @@ var SampleResultLoaderMethod = class extends LoaderMethod {
7494
7647
  return this.owner.result.runLoader(ctx.bagWith({ params: criteria }));
7495
7648
  }
7496
7649
  };
7497
- var DynamicParamsLoaderMethod = class extends LoaderMethod {
7498
- constructor(extension, owner) {
7650
+ var isZod = (value) => !!value?._zod;
7651
+ var ParamsLoaderMethod = class extends LoaderMethod {
7652
+ constructor(extension, owner, def) {
7499
7653
  super(extension, owner);
7500
7654
  this.owner = owner;
7655
+ this.def = def;
7501
7656
  }
7502
- get name() {
7503
- return dynamicParamsLoaderName(this.owner.id);
7504
- }
7657
+ #criteria;
7505
7658
  get registerAs() {
7506
7659
  return "PARAM_SCHEMA_DEFINITION";
7507
7660
  }
7508
7661
  get returnType() {
7509
- return "LIST";
7662
+ return "OBJECT";
7663
+ }
7664
+ get carryUnknown() {
7665
+ return false;
7510
7666
  }
7667
+ // Built unguarded: the picked fields were already checked on the owner, and a picked sibling may itself
7668
+ // carry `.dynamicProps()`, which the guard only allows in an action's own `params`.
7511
7669
  get criteria() {
7512
- return this.owner.dynamicParamsCriteria;
7670
+ const dependsOn = this.def.dependsOn ?? [];
7671
+ this.#criteria ??= MethodParams.of(
7672
+ z2.object(Object.fromEntries(this.owner.params.fields().filter(([name]) => dependsOn.includes(name)))),
7673
+ { serviceId: this.extension.id, kind: "loader criteria", itemId: this.name }
7674
+ );
7675
+ return this.#criteria;
7513
7676
  }
7514
7677
  async execute(criteria, ctx) {
7515
- const schema = await this.owner.resolveDynamicParams(ctx.bagWith({ criteria }));
7516
- return toBodyParams(MethodParams.of(schema, {
7517
- serviceId: this.extension.id,
7518
- kind: "action",
7519
- itemId: this.owner.id,
7520
- slot: "dynamicParams.resolve()"
7521
- }));
7678
+ const loaded = await this.def.execute(ctx.bagWith({ criteria }));
7679
+ const params = this.toParams(loaded);
7680
+ return { paramsSchema: encodeParams(params.scheme), params: toProperties(params) };
7681
+ }
7682
+ // A plain shape is wrapped in `z.object()`; anything else that is not a `z.object` is refused by the same
7683
+ // guards a declared params slot goes through.
7684
+ toParams(loaded) {
7685
+ const source = { serviceId: this.extension.id, kind: "action", itemId: this.owner.id, slot: this.slot };
7686
+ const schema = loaded && typeof loaded === "object" && !isZod(loaded) ? z2.object(loaded) : loaded;
7687
+ const returned = MethodParams.of(schema, source);
7688
+ const staticFields = this.staticFields;
7689
+ if (!staticFields.length) {
7690
+ return returned;
7691
+ }
7692
+ const staticNames = new Set(staticFields.map(([name]) => name));
7693
+ const repeated = returned.keys().filter((name) => staticNames.has(name));
7694
+ if (repeated.length) {
7695
+ throw new InvalidSchemaError(
7696
+ `[flow-extension:${this.extension.id}] action "${this.owner.id}": \`${this.slot}\` returned ${repeated.map((name) => `"${name}"`).join(", ")}, which ${repeated.length > 1 ? "are" : "is"} already declared statically. A loaded field may not replace a declared one \u2014 rename it.`,
7697
+ { ...source, received: repeated }
7698
+ );
7699
+ }
7700
+ return MethodParams.of(z2.object(Object.fromEntries([...staticFields, ...returned.fields()])), source);
7701
+ }
7702
+ };
7703
+ var DynamicParamsLoaderMethod = class extends ParamsLoaderMethod {
7704
+ constructor(extension, owner) {
7705
+ super(extension, owner, owner.dynamicParams);
7706
+ }
7707
+ get name() {
7708
+ return dynamicParamsLoaderName(this.owner.id);
7709
+ }
7710
+ get slot() {
7711
+ return "dynamicParams.execute()";
7712
+ }
7713
+ get staticFields() {
7714
+ return [];
7715
+ }
7716
+ toParams(loaded) {
7717
+ const params = super.toParams(loaded);
7718
+ const declared = new Set(this.owner.params.keys());
7719
+ const shadowing = params.keys().filter((name) => declared.has(name));
7720
+ if (shadowing.length) {
7721
+ throw new InvalidSchemaError(
7722
+ `[flow-extension:${this.extension.id}] action "${this.owner.id}": \`${this.slot}\` returned ${shadowing.map((name) => `"${name}"`).join(", ")}, which the action already declares in \`params\`. A loaded param may not shadow a declared one \u2014 rename it.`,
7723
+ { serviceId: this.extension.id, kind: "action", itemId: this.owner.id, slot: this.slot, received: shadowing }
7724
+ );
7725
+ }
7726
+ return params;
7727
+ }
7728
+ };
7729
+ var DynamicPropsLoaderMethod = class extends ParamsLoaderMethod {
7730
+ constructor(extension, owner, field, def) {
7731
+ super(extension, owner, def);
7732
+ this.field = field;
7733
+ }
7734
+ get name() {
7735
+ return dynamicPropsLoaderName(this.owner.id, this.field);
7736
+ }
7737
+ get slot() {
7738
+ return `params.${this.field}.dynamicProps().execute()`;
7739
+ }
7740
+ get staticFields() {
7741
+ const schema = this.owner.params.fields().find(([name]) => name === this.field)?.[1];
7742
+ const ins = inspect(schema);
7743
+ const object = ins.resolvedType === "array" ? ins.core?._zod?.def?.element : schema;
7744
+ return shapeEntries(inspect(object).core);
7522
7745
  }
7523
7746
  };
7524
7747
 
@@ -8431,6 +8654,9 @@ var Extension = class {
8431
8654
  if (action.hasDynamicParams()) {
8432
8655
  this.#addMethod(new DynamicParamsLoaderMethod(this, action), "dynamic params loader");
8433
8656
  }
8657
+ for (const [field, def] of action.dynamicPropsFields()) {
8658
+ this.#addMethod(new DynamicPropsLoaderMethod(this, action, field, def), "dynamic props loader");
8659
+ }
8434
8660
  }
8435
8661
  registerPollingTrigger(props) {
8436
8662
  this.#claimId(props.id, "polling trigger");
@@ -10516,6 +10742,22 @@ function writeReadme(projectRoot) {
10516
10742
  import_fs14.default.writeFileSync(fullPath, README(packageNameFrom(projectRoot)), "utf-8");
10517
10743
  return "created";
10518
10744
  }
10745
+ var JSCONFIG = {
10746
+ compilerOptions: {
10747
+ module: "node16",
10748
+ moduleResolution: "node16",
10749
+ types: [`${CLI_PACKAGE}/runtime`]
10750
+ },
10751
+ include: ["services/*/src/**/*.js"]
10752
+ };
10753
+ function writeJsconfig(projectRoot) {
10754
+ const fullPath = import_path20.default.join(projectRoot, "jsconfig.json");
10755
+ if (import_fs14.default.existsSync(fullPath)) {
10756
+ return "skipped";
10757
+ }
10758
+ import_fs14.default.writeFileSync(fullPath, JSON.stringify(JSCONFIG, null, 2) + "\n", "utf-8");
10759
+ return "created";
10760
+ }
10519
10761
  function git(projectRoot, args) {
10520
10762
  (0, import_child_process.execFileSync)("git", args, { cwd: projectRoot, stdio: "pipe" });
10521
10763
  }
@@ -10631,6 +10873,7 @@ async function init(options = {}) {
10631
10873
  const server = ensureServerUrl(projectRoot, requestedServerUrl);
10632
10874
  record2(CONFIG_FILE, server.created ? "created" : server.updated ? "updated" : "skipped");
10633
10875
  record2("README.md", writeReadme(projectRoot));
10876
+ record2("jsconfig.json", writeJsconfig(projectRoot));
10634
10877
  const testing = tests ? writeTestingFiles(projectRoot) : { created: [], skipped: [] };
10635
10878
  testing.created.forEach((file) => record2(file, "created"));
10636
10879
  testing.skipped.forEach((file) => record2(file, "skipped"));