@flowrunner/cli 0.1.18-dev.1 → 0.1.18-dev.3

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.
@@ -160,6 +160,7 @@ value is ISO: `yyyy-MM-dd`, `yyyy-MM-ddTHH:mm` (with seconds when the value had
160
160
  | `'dd/MM/yyyy HH:mm'` on `z.iso.date()` | a date has no time of day — declare `z.iso.datetime({ local: true })` |
161
161
  | `'dd/MM'` on `z.iso.time()`, `'MM/yyyy'` on `z.iso.date()` | a time has no date; every part of a date must be in its pattern |
162
162
  | `'hh:mm'` | a 12-hour clock without `a` cannot be read back — add `a`, or use `HH` |
163
+ | `'HH:mm a'` | a 24-hour clock with `a` writes `13:45 PM`, which cannot be read back — use `hh:mm a` or `HH:mm` |
163
164
  | `.dateFormat()` on `z.string()`, `z.date()`, or `z.iso.datetime()` without `{ local: true }` | only the three wall-clock types take a format |
164
165
  | `.default('2024-01-31')` with `.dateFormat('dd/MM/yyyy')` | a default is handed to `execute` as written, so write it in the field's own format: `.default('31/01/2024')` |
165
166
 
@@ -183,6 +184,14 @@ and is reshaped from the characters as written:
183
184
  yesterday's date in UTC. If the local day matters, format it in the zone you mean before it reaches the field.
184
185
  - **Blank is "not set"**, as on a number: `''`, `null` and a missing value follow `.optional()` / `.nullable()` /
185
186
  `.default()`. `.min()` / `.max()` are not available on these types.
187
+ - **A pattern made only of digits** (`yyyyMMdd`, `HHmm`) is fine: `20240131` is read as that date, and a value
188
+ that is no date in it (`20241331`) is refused like any other.
189
+ - **To let a flow clear a date**, declare a union with an empty branch:
190
+ `z.union([z.iso.date().dateFormat('dd/MM/yyyy'), z.literal('')]).optional()` (or with `z.date()`). The picker
191
+ stays; `''` (the flow sets the field to Empty Text, or binds an empty value) reaches `execute` as `''`, and an
192
+ untouched field arrives as `undefined`. Map `''` to the vendor's clear in the handler. **Never use `null` as
193
+ the clear signal**: a field left empty in a block arrives as `null`, so `.nullable()` would clear the date on
194
+ every run. This holds for `z.date()` as well — see [Clearing a value](#clearing-a-value).
186
195
  - Inside an object or a list it behaves the same, and a failure names the property (`«Days item 2» must be …`).
187
196
 
188
197
  ### Moving a field from `z.date()` to a date as text
@@ -311,7 +320,7 @@ converted:
311
320
  ```js
312
321
  limit: z.union([z.number(), z.literal('max')]) // '5' → 5 'max' → 'max'
313
322
  mode : z.union([z.boolean(), z.literal('auto')]) // 'false' → false 'auto' → 'auto'
314
- scope: z.union([z.number(), z.enum(['all', 'none'])]) // '5' → 5 'all' → 'all' 'x' → «Scope» is invalid
323
+ scope: z.union([z.number(), z.enum(['all', 'none'])]) // '5' → 5 'all' → 'all' 'x' → «Scope» must be a number, or one of: all, none
315
324
  ```
316
325
 
317
326
  Keep `z.string()` in a union only when free text really is one of the forms, and convert in the handler if
@@ -321,17 +330,33 @@ you need a number out of it. For a value that must pass through untouched whatev
321
330
  A constraint is part of "fits": `z.union([z.number().min(10), z.string()])` given `5` hands over `'5'`,
322
331
  because the number branch refuses it and the string branch takes it converted.
323
332
 
324
- ### A blank means "not set"
333
+ A value no branch accepts is refused with what **every** branch expects, in declared order: `«Scope» must be a
334
+ number, or one of: all, none`. A `z.literal('')` branch is left out, so a `''` union reads like its other
335
+ branch.
325
336
 
326
- `''` is a real value on a plain `z.string()`, which is why a cleared text box fails an optional formatted
327
- field. On a union it is absence, and that is the spelling to reach for:
337
+ ### Clearing a value
338
+
339
+ A flow sends three kinds of "nothing", and only one of them is deliberate:
340
+
341
+ | In the block | `execute` receives |
342
+ |---|---|
343
+ | the field left untouched, or cleared | `null` → absence (`undefined` under `.optional()`) |
344
+ | the **Empty Text** chip, or a bound `''` | `''` |
345
+ | a cleared text box in the **config dialog** | `''` |
346
+
347
+ `''` is a value on a plain `z.string()`. On every other type it is absence — unless you declare it with a
348
+ `z.literal('')` branch, which keeps it as a value. That is how a field lets a flow **clear** something:
328
349
 
329
350
  ```js
330
- webhookUrl: z.url().optional() // blank → «Webhook URL» is invalid — expects a URL
331
- webhookUrl: z.union([z.url(), z.literal('')]).optional() // blank → not provided
351
+ dueDate : z.union([z.date(), z.literal('')]).optional() // untouched → undefined Empty Text → '' a date → the date
352
+ webhookUrl: z.url().optional() // '' → «Webhook URL» is invalid — expects a URL
353
+ webhookUrl: z.union([z.url(), z.literal('')]).optional() // '' → '' untouched → undefined
332
354
  ```
333
355
 
334
- See [16-gotchas.md](16-gotchas.md) for the rest of that trap.
356
+ The handler decides what `''` means for the vendor: send the vendor's clear (`body.dueDate = null` when
357
+ `params.dueDate === ''`), or leave the field out (`params.webhookUrl || undefined`). Never make `null` the
358
+ clear signal — an untouched field arrives as `null`, so the vendor's value would be cleared on every run. See
359
+ [16-gotchas.md](16-gotchas.md) for the rest of that trap.
335
360
 
336
361
  ## Config fields publish a smaller set of types
337
362
 
@@ -442,6 +467,7 @@ field by its `.label()`:
442
467
  «Retries» must be at least 1
443
468
  «Site» is invalid — expects a URL, e.g. https://example.com
444
469
  «Region» must be one of: us, eu
470
+ «Scope» must be a number, or one of: all, none
445
471
  ```
446
472
 
447
473
  The console checks the *same* schema while the form is being filled in, so a config dialog reports the same
@@ -25,7 +25,8 @@ builder that prunes `''` makes the documented "leave it blank to clear it" behav
25
25
  error anywhere.
26
26
 
27
27
  **The inverse is equally sharp, and appears the moment you fix the first half.** Once `''` reaches the wire,
28
- every optional string param sends one when the flow author leaves it blank — and for an API where an absent
28
+ every optional string param sends one whenever a flow passes an empty value (a cleared config field, the Empty
29
+ Text chip, a bound `''`; a block field left untouched arrives as `null`, which is absence) — and for an API where an absent
29
30
  field means *keep the current value*, a blank one now **overwrites** it. Copy/duplicate endpoints are the
30
31
  usual place this bites: an absent caption keeps the original, an empty caption erases it.
31
32
 
@@ -41,15 +42,17 @@ documentation.
41
42
  ### The same `''` fails a format-constrained field
42
43
 
43
44
  Because `''` is a value, it reaches the format check and fails it — and `.optional()` does not help, since
44
- the field WAS provided. A cleared text box is what sends it, so this fires the first time a flow author
45
- leaves an optional URL or email blank:
45
+ the field WAS provided. A cleared config text box sends it, and so does a flow passing an empty value, so this
46
+ fires the first time someone clears an optional URL or email:
46
47
 
47
48
  ```js
48
- webhookUrl: z.url().optional().label('Webhook URL') // blank → «Webhook URL» is invalid — expects a URL
49
- webhookUrl: z.union([z.url(), z.literal('')]).optional().label('Webhook URL') // blank → not provided
49
+ webhookUrl: z.url().optional().label('Webhook URL') // '' → «Webhook URL» is invalid — expects a URL
50
+ webhookUrl: z.union([z.url(), z.literal('')]).optional().label('Webhook URL') // '' → '' (a value)
50
51
  ```
51
52
 
52
- Declare the union wherever blank has to mean "not set". A non-empty value still has to satisfy the format.
53
+ Declare the union wherever an empty value must be accepted, then decide in the handler what `''` means:
54
+ `params.webhookUrl || undefined` when empty means "not set", the vendor's clear when it means "clear it". A
55
+ non-empty value still has to satisfy the format.
53
56
 
54
57
  ## An optional object the author never filled in is absent — but may still arrive as `{}`
55
58
 
package/dist/cli.js CHANGED
@@ -14508,7 +14508,7 @@ var require_package = __commonJS({
14508
14508
  "package.json"(exports2, module2) {
14509
14509
  module2.exports = {
14510
14510
  name: "@flowrunner/cli",
14511
- version: "0.1.18-dev.1",
14511
+ version: "0.1.18-dev.3",
14512
14512
  publishConfig: {
14513
14513
  access: "public"
14514
14514
  },
@@ -15871,6 +15871,12 @@ function literalType(core) {
15871
15871
  const [kind] = [...kinds];
15872
15872
  return kinds.size === 1 && LITERAL_KINDS.has(kind) ? kind : void 0;
15873
15873
  }
15874
+ function hasBlankBranch(ins) {
15875
+ return !!ins.branches?.some((branch) => {
15876
+ const { core, coreType } = inspect(branch);
15877
+ return coreType === "literal" && (core._zod?.def?.values ?? []).includes("");
15878
+ });
15879
+ }
15874
15880
  function deriveWidget(ins) {
15875
15881
  const { coreType, core, meta } = ins;
15876
15882
  switch (coreType) {
@@ -16057,6 +16063,11 @@ function compilePattern(pattern, kind) {
16057
16063
  if (missing.length) {
16058
16064
  throw new DateFormatError(`is missing ${missing.join(", ")} \u2014 every part of a ${describeKind(kind)} must be in it`);
16059
16065
  }
16066
+ if ((names.includes("HH") || names.includes("H")) && names.includes("a")) {
16067
+ throw new DateFormatError(
16068
+ "uses a 24-hour clock (`HH` / `H`) with `a` \u2014 13:45 would be written `13:45 PM`, which cannot be read back. Use `hh` / `h` with `a`, or `HH` without it"
16069
+ );
16070
+ }
16060
16071
  if ((names.includes("hh") || names.includes("h")) && !names.includes("a")) {
16061
16072
  throw new DateFormatError(
16062
16073
  "uses a 12-hour clock (`hh` / `h`) without `a` \u2014 without AM/PM the value cannot be read back. Add `a`, or use `HH` for a 24-hour clock"
@@ -16205,7 +16216,21 @@ function canonicalToPattern(canonical, ins, kind) {
16205
16216
  const parts = parseIso(canonical, kind);
16206
16217
  return parts ? formatParts(parts, pattern, kind) : canonical;
16207
16218
  }
16208
- var isTimestamp = (value) => typeof value === "number" && Number.isFinite(value) || typeof value === "string" && /^-?\d+(\.\d+)?$/.test(value.trim());
16219
+ var MIN_TIMESTAMP_DIGITS = 13;
16220
+ function digitOnlyLength(pattern, kind) {
16221
+ const example = formatParts(EXAMPLE, pattern, kind);
16222
+ return /^\d+$/.test(example) ? example.length : void 0;
16223
+ }
16224
+ function isTimestamp(value, pattern, kind) {
16225
+ if (typeof value === "number") {
16226
+ return Number.isFinite(value);
16227
+ }
16228
+ if (typeof value !== "string") {
16229
+ return false;
16230
+ }
16231
+ const text2 = value.trim();
16232
+ return new RegExp(`^\\d{${MIN_TIMESTAMP_DIGITS},}$`).test(text2) && digitOnlyLength(pattern, kind) !== text2.length;
16233
+ }
16209
16234
  function timestampParts(value, kind) {
16210
16235
  const date = new Date(Number(value));
16211
16236
  if (Number.isNaN(date.getTime())) {
@@ -16222,15 +16247,15 @@ function timestampParts(value, kind) {
16222
16247
  }, kind);
16223
16248
  }
16224
16249
  function toDateString(value, ins, kind) {
16225
- if (typeof value === "string") {
16226
- const text2 = value.trim();
16227
- const pattern = ins.meta.frDateFormat;
16228
- const parts = (pattern ? parseInPattern(text2, pattern, kind) : void 0) ?? parseIso(text2, kind);
16250
+ const pattern = ins.meta.frDateFormat;
16251
+ const text2 = typeof value === "string" ? value.trim() : typeof value === "number" && Number.isInteger(value) && value >= 0 ? String(value) : void 0;
16252
+ if (text2 !== void 0) {
16253
+ const parts = (pattern ? parseInPattern(text2, pattern, kind) : void 0) ?? (typeof value === "string" ? parseIso(text2, kind) : void 0);
16229
16254
  if (parts) {
16230
16255
  return { canonical: toCanonical(parts, kind) };
16231
16256
  }
16232
16257
  }
16233
- if (DATE_STRINGS_ACCEPT_TIMESTAMPS && isTimestamp(value)) {
16258
+ if (DATE_STRINGS_ACCEPT_TIMESTAMPS && isTimestamp(value, patternOf(ins, kind), kind)) {
16234
16259
  const parts = timestampParts(value, kind);
16235
16260
  return parts ? { canonical: toCanonical(parts, kind), fromTimestamp: true } : {};
16236
16261
  }
@@ -16735,6 +16760,7 @@ function planField(name, schema) {
16735
16760
  label: labelOf(name, schema),
16736
16761
  coreType: ins.coreType,
16737
16762
  isUnion: !!ins.branches,
16763
+ blankBranch: hasBlankBranch(ins),
16738
16764
  absence,
16739
16765
  absorbsBlank,
16740
16766
  keepsEmpty,
@@ -16987,7 +17013,7 @@ function isBlank(value, ins, schema) {
16987
17013
  return false;
16988
17014
  }
16989
17015
  if (ins.branches) {
16990
- return true;
17016
+ return !hasBlankBranch(ins) || absenceOf(schema).absorbsBlank;
16991
17017
  }
16992
17018
  if (absenceOf(schema).blankIsValue) {
16993
17019
  return absenceOf(schema).absorbsBlank;
@@ -17056,6 +17082,72 @@ var EXPECTED = {
17056
17082
  record: "an object"
17057
17083
  };
17058
17084
  var requiredMessage = (plan2) => `\xAB${plan2.label}\xBB is required`;
17085
+ var oneOf = (values) => `one of: ${values.map(String).join(", ")}`;
17086
+ var formatPhrase = (format) => {
17087
+ const described = FORMAT_DESCRIPTIONS[format ?? ""];
17088
+ return described?.replace(/^Expects (.*?), e\.g\. (.*)$/, "$1 (e.g. $2)").replace(/^Expects /, "");
17089
+ };
17090
+ var distinct = (phrases) => [...new Set(phrases.filter((phrase) => !!phrase))];
17091
+ function unionPhrases(union, value) {
17092
+ return distinct((inspect(union).branches ?? []).map((branch) => {
17093
+ try {
17094
+ const result = branch.safeParse(value);
17095
+ return branchPhrase(branch, result.error?.issues[0]);
17096
+ } catch {
17097
+ return void 0;
17098
+ }
17099
+ }));
17100
+ }
17101
+ function remainingIssue(branch, value) {
17102
+ if (!branch) {
17103
+ return void 0;
17104
+ }
17105
+ try {
17106
+ const result = branch.safeParse(coerceDeep(value, branch));
17107
+ return result.success ? void 0 : result.error?.issues[0];
17108
+ } catch {
17109
+ return void 0;
17110
+ }
17111
+ }
17112
+ function branchPhrase(branch, issue) {
17113
+ if (!branch || !issue) {
17114
+ return void 0;
17115
+ }
17116
+ const ins = inspect(branch);
17117
+ const values = ins.core._zod?.def?.values ?? [];
17118
+ if (ins.coreType === "literal" && values.length === 1 && values[0] === "") {
17119
+ return void 0;
17120
+ }
17121
+ const dateKind = dateStringKind(ins);
17122
+ if (dateKind) {
17123
+ return expectedDateString(ins, dateKind);
17124
+ }
17125
+ switch (issue.code) {
17126
+ case "invalid_type":
17127
+ return EXPECTED[issue.expected ?? ""] ?? issue.expected;
17128
+ case "invalid_value":
17129
+ return oneOf(issue.values ?? values);
17130
+ case "invalid_format":
17131
+ return formatPhrase(issue.format);
17132
+ // A bound has no short phrase ("a number of at least 10"); the branch still names its type.
17133
+ case "too_small":
17134
+ case "too_big":
17135
+ return EXPECTED[ins.coreType === "literal" ? literalType(ins.core) ?? "" : ins.coreType];
17136
+ default:
17137
+ return void 0;
17138
+ }
17139
+ }
17140
+ function unionIssue(plan2, issue, union, unionValue, fieldValue) {
17141
+ const branches = union ? inspect(union).branches : void 0;
17142
+ const errors = issue.errors ?? [];
17143
+ const deepIndex = errors.findIndex((branchIssues) => branchIssues.some((branchIssue) => (branchIssue.path ?? []).length));
17144
+ if (deepIndex >= 0) {
17145
+ const deep = remainingIssue(branches?.[deepIndex], unionValue) ?? errors[deepIndex].find((branchIssue) => (branchIssue.path ?? []).length);
17146
+ return toFieldIssue(plan2, { ...deep, path: [...issue.path ?? [], ...deep.path ?? []] }, fieldValue);
17147
+ }
17148
+ const phrases = distinct(errors.map((branchIssues, index) => branchPhrase(branches?.[index], branchIssues[0])));
17149
+ return phrases.length ? { path: "", code: "invalid_union", message: `must be ${phrases.join(", or ")}` } : void 0;
17150
+ }
17059
17151
  var invalidTypeMessage = (plan2, expected) => `\xAB${plan2.label}\xBB must be ${EXPECTED[expected] ?? expected}`;
17060
17152
  var isIndex = (segment) => /^\d+$/.test(segment);
17061
17153
  function resolveTarget(plan2, segments, fieldValue) {
@@ -17102,6 +17194,12 @@ function toFieldIssue(plan2, issue, fieldValue) {
17102
17194
  if (isAuthored(issue)) {
17103
17195
  return { path: path23, code, message: issue.message };
17104
17196
  }
17197
+ if (code !== "invalid_union" && target.schema && inspect(target.schema).branches) {
17198
+ const combined = unionPhrases(target.schema, target.value);
17199
+ if (combined.length > 1) {
17200
+ return { path: path23, code: "invalid_union", message: `\xAB${target.label}\xBB must be ${combined.join(", or ")}` };
17201
+ }
17202
+ }
17105
17203
  const dateKind = target.schema ? dateStringKind(inspect(target.schema)) : void 0;
17106
17204
  const dateMissing = target.value == null || target.value === "";
17107
17205
  if (dateKind && (code === "invalid_type" || code === "invalid_format")) {
@@ -17119,13 +17217,18 @@ function toFieldIssue(plan2, issue, fieldValue) {
17119
17217
  return { path: path23, code, message: `\xAB${target.label}\xBB must be at most ${bound(issue.maximum, plan2)}` };
17120
17218
  }
17121
17219
  if (code === "invalid_value") {
17122
- const values = (issue.values ?? []).map(String);
17123
- return { path: path23, code, message: `\xAB${target.label}\xBB must be one of: ${values.join(", ")}` };
17220
+ return { path: path23, code, message: `\xAB${target.label}\xBB must be ${oneOf(issue.values ?? [])}` };
17124
17221
  }
17125
17222
  if (code === "invalid_format") {
17126
17223
  const described = FORMAT_DESCRIPTIONS[issue.format ?? ""];
17127
17224
  return described ? { path: path23, code, message: `\xAB${target.label}\xBB is invalid \u2014 ${described.replace(/^Expects /, "expects ")}` } : { path: path23, code, message: `\xAB${target.label}\xBB has an invalid format` };
17128
17225
  }
17226
+ if (code === "invalid_union") {
17227
+ const combined = unionIssue(plan2, issue, target.schema, target.value, fieldValue);
17228
+ if (combined) {
17229
+ return combined.path ? combined : { path: path23, code, message: `\xAB${target.label}\xBB ${combined.message}` };
17230
+ }
17231
+ }
17129
17232
  return { path: path23, code, message: `\xAB${target.label}\xBB is invalid` };
17130
17233
  }
17131
17234
 
@@ -17146,7 +17249,7 @@ function isAbsent(value, plan2) {
17146
17249
  return false;
17147
17250
  }
17148
17251
  if (plan2.isUnion) {
17149
- return true;
17252
+ return !plan2.blankBranch || plan2.absorbsBlank;
17150
17253
  }
17151
17254
  if (plan2.blankIsValue) {
17152
17255
  return plan2.absorbsBlank;
@@ -18291,7 +18394,19 @@ var ExecutionContext = class _ExecutionContext {
18291
18394
  return this.#options.invocation ?? {};
18292
18395
  }
18293
18396
  get config() {
18294
- this.#config ??= this.#extension.config.resolve(this.#options.configs);
18397
+ if (!this.#config) {
18398
+ const { result, notices } = collectNotices(() => this.#extension.config.resolve(this.#options.configs));
18399
+ for (const { message, field, value, converted } of notices) {
18400
+ this.logger.warn(`[flow-extension:${this.#extension.id}] config item "${field ?? "?"}": ${message}`, {
18401
+ serviceId: this.#extension.id,
18402
+ configItem: field,
18403
+ value,
18404
+ converted,
18405
+ ...this.invocation
18406
+ });
18407
+ }
18408
+ this.#config = result;
18409
+ }
18295
18410
  return this.#config;
18296
18411
  }
18297
18412
  // The header access token plus its deserialized composite payload — or a throwing proxy when the