@flowrunner/cli 0.1.16 → 0.1.18

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 (25) hide show
  1. package/ai-docs/instructions/service-code-format/02-zod-types.md +87 -29
  2. package/ai-docs/instructions/service-code-format/03-parameters.md +3 -1
  3. package/ai-docs/instructions/service-code-format/05-dictionaries.md +8 -2
  4. package/ai-docs/instructions/service-code-format/07-actions.md +5 -1
  5. package/ai-docs/instructions/service-code-format/14-reference-service.md +1 -1
  6. package/ai-docs/instructions/service-code-format/16-gotchas.md +90 -0
  7. package/ai-docs/instructions/service-code-format/18-test-recipes.md +2 -1
  8. package/ai-docs/instructions/service-code-format/README.md +1 -1
  9. package/dist/cli.js +61 -47
  10. package/dist/cli.js.map +3 -3
  11. package/dist/index.js +60 -46
  12. package/dist/index.js.map +3 -3
  13. package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
  14. package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -11
  15. package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
  16. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +9 -19
  17. package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -1
  18. package/package.json +1 -1
  19. package/runtime/index.js +60 -46
  20. package/runtime/index.js.map +3 -3
  21. package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
  22. package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -11
  23. package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
  24. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +9 -19
  25. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -1
@@ -4,7 +4,7 @@ export declare const DictionaryPayloadSchema: import("zod").ZodObject<{
4
4
  criteria: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
5
5
  }, import("zod/v4/core").$loose>;
6
6
  export interface DictionaryPayload {
7
- search?: string;
7
+ search: string;
8
8
  cursor?: unknown;
9
9
  criteria: Record<string, unknown>;
10
10
  }
@@ -1,12 +1,6 @@
1
1
  import { type AnyZod } from './introspect';
2
2
  /** `z.text()` — FlowRunner's own marker, the most specific thing a field can declare. */
3
3
  export declare const WIDGET_DESCRIPTIONS: Record<string, string>;
4
- /**
5
- * `z.json()`. More specific than the widget it carries: it renders as the same textarea `z.text()` does, so
6
- * the widget wording would say "line breaks are allowed" and leave out the only rule that actually rejects
7
- * anything — that what is typed has to parse.
8
- */
9
- export declare const JSON_DESCRIPTION = "Expects JSON, e.g. {\"key\": \"value\"}";
10
4
  /**
11
5
  * The plain core type, when nothing more specific is declared.
12
6
  *
@@ -26,11 +20,10 @@ export declare const FORMAT_DESCRIPTIONS: Record<string, string>;
26
20
  /**
27
21
  * What a field's declaration explains about itself, most specific wins:
28
22
  *
29
- * 1. `z.json()` — the content rule, which outranks the widget it shares with `z.text()`
30
- * 2. a FlowRunner widget marker — `z.text()`, a string the console renders specially
31
- * 3. a zod `format` token — `z.email()`, `z.ipv4()`, `z.iso.date()`, …
32
- * 4. the plain core type — `number`, `bigint`, `literal`, `enum`, `date`
23
+ * 1. a FlowRunner widget marker — `z.text()`, a string the console renders specially
24
+ * 2. a zod `format` token — `z.email()`, `z.ipv4()`, `z.iso.date()`, …
25
+ * 3. the plain core type — `number`, `bigint`, `literal`, `enum`, `date`
33
26
  *
34
- * All three are read past the optional/nullable/default wrappers, so a modifier never changes the answer.
27
+ * Each is read past the optional/nullable/default wrappers, so a modifier never changes the answer.
35
28
  */
36
29
  export declare function describeField(schema: AnyZod): string | undefined;
@@ -33,7 +33,7 @@ export declare const FlowExtensionParamWidgetTypes: {
33
33
  * The widget tokens a declaration carries EXPLICITLY, as author metadata (`meta.frWidget`) — everything else
34
34
  * in the map above is DERIVED from the zod type by `deriveWidget`.
35
35
  *
36
- * `MULTI_LINE_TEXT` is `z.text()` / `z.json()`; the `FILE_*_OPTIONS` tokens name a platform param group.
36
+ * `MULTI_LINE_TEXT` is `z.text()`; the `FILE_*_OPTIONS` tokens name a platform param group.
37
37
  */
38
38
  export type FrWidgetToken = 'MULTI_LINE_TEXT' | 'FILE_UPLOAD_OPTIONS' | 'FILE_LIST_OPTIONS' | 'FILE_GET_OPTIONS' | 'FILE_DELETE_OPTIONS';
39
39
  /** The subset that names a platform param GROUP rather than a single control. */
@@ -33,8 +33,6 @@ export interface FrMeta {
33
33
  /** A widget token the declaration carries explicitly — see `FrWidgetToken` in ./widget-types.ts. */
34
34
  frWidget?: FrWidgetToken;
35
35
  frSecret?: boolean;
36
- /** `z.json()` — the value arrives as TEXT and is parsed before the handler sees it. See `json()` below. */
37
- frJson?: boolean;
38
36
  /**
39
37
  * `.dynamicProps()` — the spec (holding the author's function) on a declared schema, the plain ref of the
40
38
  * method that runs it on a decoded one. Never encoded as the spec: see ./json/encode.ts.
@@ -98,25 +96,17 @@ declare module 'zod' {
98
96
  }
99
97
  declare function text(): baseZod.ZodString;
100
98
  /**
101
- * Custom type: a parameter that takes arbitrary JSON.
99
+ * `z.json()` is not a param type. It was one — JSON typed into a textarea, parsed before the handler ran — and
100
+ * was removed (FR-3910): `z.unknown()` takes any value as given, and a declared `z.object()` / `z.array()` takes
101
+ * JSON text of its kind (see ./schema/coerce.ts), so the only thing it still offered was a parse of free text
102
+ * into a value nobody had described.
102
103
  *
103
- * Three facts have to hold at once, and each picks one piece of this declaration:
104
- *
105
- * - **The console renders a textarea.** `frWidget` says so, and ../schema/introspect.ts publishes the
106
- * parameter as `STRING` — the model describes what a caller SUPPLIES, and what a caller supplies is text.
107
- * - **`execute` receives the parsed structure.** `frJson` tells ../schema/coerce.ts to `JSON.parse` the text
108
- * on the way in, so no service writes its own parse and none has to invent wording for text that is not
109
- * JSON. Coercion already sits between the transport and zod for exactly this kind of conversion — this is
110
- * the same arrangement as `z.string().pipe(z.coerce.number())`, with a fixed conversion.
111
- * - **The author's TYPE is the parsed value, not the text.** Hence `unknown` underneath: `z.infer` gives the
112
- * handler `unknown`, which is what it actually receives. Declaring `z.string()` here would publish and
113
- * coerce correctly and then lie to every author about what lands in `params`.
114
- *
115
- * ⚠️ This SHADOWS zod's own `z.json()` (the namespace is `Object.create(baseZod)`). Deliberate, and safe
116
- * only because zod's version cannot currently be declared at all — it recurses until the stack is gone, and
117
- * the extension never registers (FR-3600). An author reaching for `z.json()` gets this one.
104
+ * It throws rather than disappearing, because the name would otherwise fall through to zod's own `z.json()`
105
+ * (the namespace is `Object.create(baseZod)`), which cannot be declared at all: it recurses until the stack is
106
+ * gone and the extension never registers (FR-3600). An author following an old example gets a message naming
107
+ * what to write instead, at registration, instead of a stack overflow.
118
108
  */
119
- declare function json(): baseZod.ZodNonOptional<baseZod.ZodUnknown>;
109
+ declare function json(): never;
120
110
  export declare const z: Omit<typeof baseZod, "json"> & {
121
111
  text: typeof text;
122
112
  json: typeof json;
@@ -90,7 +90,7 @@ export interface DictionaryProps<TShape extends ExtensionShape = AnyShape, TCrit
90
90
  result?: unknown;
91
91
  oauth2Scopes?: string[];
92
92
  execute: (bag: HandlerBag<TShape> & {
93
- search?: string;
93
+ search: string;
94
94
  cursor?: unknown;
95
95
  criteria: Infer<TCriteria>;
96
96
  }) => DictionaryResult | DictionaryResultItems | Promise<DictionaryResult | DictionaryResultItems>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flowrunner/cli",
3
- "version": "0.1.16",
3
+ "version": "0.1.18",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
package/runtime/index.js CHANGED
@@ -12082,9 +12082,6 @@ function literalType(core) {
12082
12082
  }
12083
12083
  function deriveWidget(ins) {
12084
12084
  const { coreType, core, meta } = ins;
12085
- if (meta.frJson) {
12086
- return { paramType: "STRING", uiComponent: { type: FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT } };
12087
- }
12088
12085
  switch (coreType) {
12089
12086
  case "string":
12090
12087
  if (meta.frWidget === FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT) {
@@ -12474,7 +12471,6 @@ function declaredAbsence(schema) {
12474
12471
  function coerces(schema) {
12475
12472
  return inspect(schema).core?._zod?.def?.coerce === true;
12476
12473
  }
12477
- var parsesJson = (schema) => !!inspect(schema).meta.frJson;
12478
12474
  var OPEN_TYPES = /* @__PURE__ */ new Set(["unknown", "any"]);
12479
12475
  var isOpenType = (schema) => OPEN_TYPES.has(inspect(schema).coreType);
12480
12476
  function requiredOpenType(schema) {
@@ -12496,7 +12492,7 @@ function requiredOpenType(schema) {
12496
12492
  return false;
12497
12493
  }
12498
12494
  function probeAbsence(schema) {
12499
- if (coerces(schema) || parsesJson(schema)) {
12495
+ if (coerces(schema)) {
12500
12496
  return declaredAbsence(schema);
12501
12497
  }
12502
12498
  if (requiredOpenType(schema)) {
@@ -12523,7 +12519,7 @@ function absenceOf(schema) {
12523
12519
  if (cached) {
12524
12520
  return cached;
12525
12521
  }
12526
- const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) && !parsesJson(schema) };
12522
+ const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) };
12527
12523
  probeCache.set(schema, probed);
12528
12524
  return probed;
12529
12525
  }
@@ -12557,8 +12553,29 @@ function toStringValue(value) {
12557
12553
  if (typeof value === "boolean") {
12558
12554
  return ok(String(value));
12559
12555
  }
12556
+ if (value !== null && typeof value === "object") {
12557
+ return ok(value instanceof Date ? value.toISOString() : JSON.stringify(value));
12558
+ }
12560
12559
  return typeof value === "number" && Number.isFinite(value) ? ok(String(value)) : fail("string");
12561
12560
  }
12561
+ var OPENS = { array: "[", object: "{" };
12562
+ function parseContainerText(value, kind) {
12563
+ if (typeof value !== "string") {
12564
+ return value;
12565
+ }
12566
+ const text2 = value.trim();
12567
+ if (!text2.startsWith(OPENS[kind])) {
12568
+ return value;
12569
+ }
12570
+ try {
12571
+ const parsed = JSON.parse(text2);
12572
+ const isList = Array.isArray(parsed);
12573
+ const fits = kind === "array" ? isList : parsed !== null && typeof parsed === "object" && !isList;
12574
+ return fits ? parsed : value;
12575
+ } catch {
12576
+ return value;
12577
+ }
12578
+ }
12562
12579
  function toNumberValue(value) {
12563
12580
  if (typeof value === "number") {
12564
12581
  return Number.isFinite(value) ? ok(value) : fail("number");
@@ -12598,16 +12615,6 @@ function toBooleanValue(value) {
12598
12615
  const lowered = value.trim().toLowerCase();
12599
12616
  return TRUE.has(lowered) ? ok(true) : FALSE.has(lowered) ? ok(false) : fail("boolean");
12600
12617
  }
12601
- function toJsonValue(value) {
12602
- if (typeof value !== "string") {
12603
- return ok(value);
12604
- }
12605
- try {
12606
- return ok(JSON.parse(value));
12607
- } catch {
12608
- return fail("json");
12609
- }
12610
- }
12611
12618
  function coerceValue(value, coreType) {
12612
12619
  if (coreType === "string") {
12613
12620
  return toStringValue(value);
@@ -12641,7 +12648,11 @@ function coerceUnion(value, branches) {
12641
12648
  if (branches.some((branch) => accepts(branch, value))) {
12642
12649
  return value;
12643
12650
  }
12651
+ const isStructure = value !== null && typeof value === "object";
12644
12652
  for (const branch of branches) {
12653
+ if (isStructure && inspect(branch).coreType === "string") {
12654
+ continue;
12655
+ }
12645
12656
  const coerced = coerceDeep(value, branch);
12646
12657
  if (accepts(branch, coerced)) {
12647
12658
  return coerced;
@@ -12666,22 +12677,25 @@ function coerceDeep(value, schema) {
12666
12677
  }
12667
12678
  if (ins.coreType === "array") {
12668
12679
  const element = ins.core?._zod?.def?.element;
12669
- return Array.isArray(value) ? value.map((item) => coerceDeep(item, element)) : value;
12680
+ const list = parseContainerText(value, "array");
12681
+ return Array.isArray(list) ? list.map((item) => coerceDeep(item, element)) : list;
12670
12682
  }
12671
12683
  if (ins.coreType === "record") {
12672
- if (typeof value !== "object" || Array.isArray(value)) {
12673
- return value;
12684
+ const map = parseContainerText(value, "object");
12685
+ if (typeof map !== "object" || Array.isArray(map)) {
12686
+ return map;
12674
12687
  }
12675
12688
  const valueType = ins.core?._zod?.def?.valueType;
12676
12689
  return Object.fromEntries(
12677
- Object.entries(value).map(([key, item]) => [key, coerceDeep(item, valueType)])
12690
+ Object.entries(map).map(([key, item]) => [key, coerceDeep(item, valueType)])
12678
12691
  );
12679
12692
  }
12680
12693
  if (ins.coreType === "object") {
12681
- if (typeof value !== "object" || Array.isArray(value)) {
12682
- return value;
12694
+ const parsed = parseContainerText(value, "object");
12695
+ if (typeof parsed !== "object" || Array.isArray(parsed)) {
12696
+ return parsed;
12683
12697
  }
12684
- const source = value;
12698
+ const source = parsed;
12685
12699
  const coerced = { ...source };
12686
12700
  for (const [name, property] of shapeEntries(ins.core)) {
12687
12701
  if (name in source) {
@@ -12698,9 +12712,6 @@ function coerceLeaf(value, ins) {
12698
12712
  if (ins.branches) {
12699
12713
  return ok(coerceUnion(value, ins.branches));
12700
12714
  }
12701
- if (ins.meta.frJson) {
12702
- return toJsonValue(value);
12703
- }
12704
12715
  const format = formatOf(ins);
12705
12716
  if (ins.coreType === "string" && isConvertibleIso(format)) {
12706
12717
  const iso = toIso(value, format);
@@ -12794,8 +12805,8 @@ var EXPECTED = {
12794
12805
  date: "a date",
12795
12806
  object: "an object",
12796
12807
  array: "an array",
12797
- // `z.json()`. Not a zod token — ./coerce.ts raises it when the submitted text will not parse.
12798
- json: "valid JSON"
12808
+ // zod's own token for `z.record()`, which the author declared as a map — to a person it is an object.
12809
+ record: "an object"
12799
12810
  };
12800
12811
  var requiredMessage = (plan) => `\xAB${plan.label}\xBB is required`;
12801
12812
  var invalidTypeMessage = (plan, expected) => `\xAB${plan.label}\xBB must be ${EXPECTED[expected] ?? expected}`;
@@ -13213,10 +13224,9 @@ function text() {
13213
13224
  return import_zod2.z.string().meta({ frWidget: FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT });
13214
13225
  }
13215
13226
  function json() {
13216
- return import_zod2.z.unknown().nonoptional().meta({
13217
- frWidget: FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT,
13218
- frJson: true
13219
- });
13227
+ throw new Error(
13228
+ "`z.json()` is not supported \u2014 declare `z.unknown()` for any value passed as given (`.required()` to make it required), or declare the shape: `z.object({ \u2026 })` / `z.array(\u2026)` also accept JSON text and parse it."
13229
+ );
13220
13230
  }
13221
13231
  var namespace = Object.create(import_zod2.z);
13222
13232
  Object.defineProperties(namespace, {
@@ -13230,7 +13240,7 @@ Object.defineProperties(namespace, {
13230
13240
  var z = namespace;
13231
13241
 
13232
13242
  // ../../flow-extension-runner/src/v2/params/json/values.ts
13233
- function toJsonValue2(value) {
13243
+ function toJsonValue(value) {
13234
13244
  if (typeof value === "bigint") {
13235
13245
  return { $bigint: value.toString() };
13236
13246
  }
@@ -13238,10 +13248,10 @@ function toJsonValue2(value) {
13238
13248
  return { $date: value.toISOString() };
13239
13249
  }
13240
13250
  if (Array.isArray(value)) {
13241
- return value.map(toJsonValue2);
13251
+ return value.map(toJsonValue);
13242
13252
  }
13243
13253
  if (value && typeof value === "object") {
13244
- return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, toJsonValue2(inner)]));
13254
+ return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, toJsonValue(inner)]));
13245
13255
  }
13246
13256
  return value;
13247
13257
  }
@@ -13276,18 +13286,18 @@ function encodeCheck(check) {
13276
13286
  switch (def.check) {
13277
13287
  // strings and arrays
13278
13288
  case "min_length":
13279
- return at("min", toJsonValue2(def.minimum));
13289
+ return at("min", toJsonValue(def.minimum));
13280
13290
  case "max_length":
13281
- return at("max", toJsonValue2(def.maximum));
13291
+ return at("max", toJsonValue(def.maximum));
13282
13292
  case "length_equals":
13283
- return at("length", toJsonValue2(def.length));
13293
+ return at("length", toJsonValue(def.length));
13284
13294
  // numbers and bigints
13285
13295
  case "greater_than":
13286
- return at("min", toJsonValue2(def.value), def.inclusive ? void 0 : true);
13296
+ return at("min", toJsonValue(def.value), def.inclusive ? void 0 : true);
13287
13297
  case "less_than":
13288
- return at("max", toJsonValue2(def.value), def.inclusive ? void 0 : true);
13298
+ return at("max", toJsonValue(def.value), def.inclusive ? void 0 : true);
13289
13299
  case "multiple_of":
13290
- return at("multipleOf", toJsonValue2(def.value));
13300
+ return at("multipleOf", toJsonValue(def.value));
13291
13301
  case "number_format":
13292
13302
  return def.format === "safeint" || def.format === "int32" ? at("int") : void 0;
13293
13303
  // the string sub-formats that are checks rather than types
@@ -13448,7 +13458,7 @@ function encodeMeta(meta, field, scope2, loaderId) {
13448
13458
  if (hasFunction(source)) {
13449
13459
  throw new Error(`Cannot encode "${field}": its metadata holds a function, which has no wire form.`);
13450
13460
  }
13451
- const encoded = toJsonValue2(source);
13461
+ const encoded = toJsonValue(source);
13452
13462
  return Object.keys(encoded).length ? encoded : void 0;
13453
13463
  }
13454
13464
  function isLoose(core) {
@@ -13458,11 +13468,11 @@ function isLoose(core) {
13458
13468
  function encodeValues(core, type) {
13459
13469
  if (type === "enum") {
13460
13470
  const entries = core?._zod?.def?.entries ?? {};
13461
- return Object.values(entries).map(toJsonValue2);
13471
+ return Object.values(entries).map(toJsonValue);
13462
13472
  }
13463
13473
  if (type === "literal") {
13464
13474
  const values = core?._zod?.def?.values ?? [];
13465
- return values.map(toJsonValue2);
13475
+ return values.map(toJsonValue);
13466
13476
  }
13467
13477
  return void 0;
13468
13478
  }
@@ -13492,7 +13502,7 @@ function encodeField(name, schema, seen = /* @__PURE__ */ new Set(), loaderId, s
13492
13502
  ...format ? { format } : {},
13493
13503
  ...optional ? { optional: true } : {},
13494
13504
  ...nullable ? { nullable: true } : {},
13495
- ...hasDefault ? { default: toJsonValue2(defaultValue) } : {},
13505
+ ...hasDefault ? { default: toJsonValue(defaultValue) } : {},
13496
13506
  ...checks.length ? { checks } : {},
13497
13507
  ...values?.length ? { values } : {},
13498
13508
  ...meta ? { meta } : {},
@@ -14294,6 +14304,10 @@ var DictionaryMethod = class extends ExtensionMethod {
14294
14304
  return this.criteria.keys();
14295
14305
  }
14296
14306
  // ── runtime ────────────────────────────────────────────────────────────────
14307
+ // `search` is always text, trimmed (FR-3910): `''` when the author typed nothing — the console then sends no
14308
+ // `search` at all — or only spaces. So a handler never guards it: `search ? { q: search } : undefined`, and
14309
+ // `search.toLowerCase()` as is. Surrounding spaces never mean anything to a lookup.
14310
+ //
14297
14311
  // Two-stage: the `{ search, cursor, criteria }` envelope the runtime owns, then the author-declared
14298
14312
  // criteria through the shared pipeline — reported as a criteria failure so the console can point at the
14299
14313
  // dependent fields rather than the whole call.
@@ -14302,7 +14316,7 @@ var DictionaryMethod = class extends ExtensionMethod {
14302
14316
  const payload = input.parseField("payload", DictionaryPayloadSchema);
14303
14317
  const criteria = this.criteria.normalize(this.#resolveAliases(payload.criteria), input.invalidCriteria());
14304
14318
  return {
14305
- search: payload.search,
14319
+ search: payload.search?.trim() ?? "",
14306
14320
  cursor: payload.cursor,
14307
14321
  criteria
14308
14322
  };