@flowrunner/cli 0.1.16 → 0.1.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ai-docs/instructions/service-code-format/02-zod-types.md +37 -3
- package/ai-docs/instructions/service-code-format/07-actions.md +4 -0
- package/ai-docs/instructions/service-code-format/16-gotchas.md +31 -0
- package/dist/cli.js +38 -8
- package/dist/cli.js.map +3 -3
- package/dist/index.js +37 -7
- package/dist/index.js.map +3 -3
- package/package.json +1 -1
- package/runtime/index.js +37 -7
- package/runtime/index.js.map +3 -3
|
@@ -89,7 +89,8 @@ but the runtime parses it before your handler runs, and `execute` receives the p
|
|
|
89
89
|
|
|
90
90
|
`z.json()` declares nothing about the value's SHAPE. When you do know the shape, declare it — a
|
|
91
91
|
`z.object({ … })` gives the user a real form and gives you a checked value, where this gives a textarea and
|
|
92
|
-
`unknown`.
|
|
92
|
+
`unknown`. A declared `z.object()` / `z.array()` also takes JSON text (see
|
|
93
|
+
[Text and structures](#text-and-structures)), so you lose nothing by declaring the shape.
|
|
93
94
|
|
|
94
95
|
## The type list is CLOSED
|
|
95
96
|
|
|
@@ -257,7 +258,7 @@ The two other differences are structural:
|
|
|
257
258
|
|
|
258
259
|
| Declared in `configItems` | What happens |
|
|
259
260
|
|---|---|
|
|
260
|
-
| `z.object({...})`, `z.array(inner)` | **
|
|
261
|
+
| `z.object({...})`, `z.array(inner)` | **a plain text box** that takes the value as JSON text (`{"region":"eu"}`, `["a","b"]`), parsed and checked like any object or list — see [Text and structures](#text-and-structures). Usable, but a poor form: prefer a param for structured input |
|
|
261
262
|
| `.dictionary(ref)` | **ignored** — a config value is resolved before any method runs, so there is no invocation to fetch options for. Use `z.enum([...])` for a fixed set of choices |
|
|
262
263
|
|
|
263
264
|
`z.date()` in a config field is a date, with no time of day. Declare a string if you need one.
|
|
@@ -267,6 +268,36 @@ conversion.** `z.coerce.*` does not add to it, so `z.coerce.number()` and `z.num
|
|
|
267
268
|
as do the boolean and string forms. The one exception is `z.date()` — declare **`z.coerce.date()`** when your handler wants a real `Date`
|
|
268
269
|
instance rather than the string or epoch-millis the caller sent.
|
|
269
270
|
|
|
271
|
+
### Text and structures
|
|
272
|
+
|
|
273
|
+
Text and structured values convert into each other, so a value survives a trip through a text box or an
|
|
274
|
+
expression either way:
|
|
275
|
+
|
|
276
|
+
- **A text field takes any value.** An object or a list given to `z.string()`, `z.text()` or a format becomes
|
|
277
|
+
its JSON text. `null` and a missing value are still blanks, never the text `'null'`.
|
|
278
|
+
- **An object or list field takes JSON text.** Text given to `z.object()`, `z.looseObject()`, `z.record()` or
|
|
279
|
+
`z.array()` is parsed when it is JSON of the matching kind — `{…}` for an object or record, `[…]` for a list —
|
|
280
|
+
and then converted and checked like any other value.
|
|
281
|
+
|
|
282
|
+
```js
|
|
283
|
+
note : z.string() // { a: 1 } → '{"a":1}'
|
|
284
|
+
title: z.string().max(5) // { a: 1 } → «Title» must be at most 5 (checks run on the text)
|
|
285
|
+
point: z.object({ x: z.number() }) // '{"x":"1"}' → { x: 1 }
|
|
286
|
+
ids : z.array(z.number()) // '[1,"2"]' → [1, 2]
|
|
287
|
+
ids : z.array(z.number()) // '1,2' → «Ids» must be an array (not JSON — not split)
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Anything that is not JSON of the right kind is refused as before: a comma-separated value is not split for
|
|
291
|
+
you, and `'{a:1}'` (unquoted key) is not JSON. `''` is still a blank; `'{}'` and `'[]'` are values.
|
|
292
|
+
|
|
293
|
+
In a union, a value that already fits a branch is kept (see above), and an object or a list is **never** turned
|
|
294
|
+
into text through a `z.string()` branch: it takes a branch of its own kind or the union's error, so a malformed
|
|
295
|
+
object is reported rather than sent as JSON text. `z.json()` is unchanged — use it for JSON whose shape you do
|
|
296
|
+
not declare.
|
|
297
|
+
|
|
298
|
+
The flip side: an object bound by mistake to a plain text field (a subject, a name) is sent as JSON text
|
|
299
|
+
rather than refused.
|
|
300
|
+
|
|
270
301
|
### What a boolean accepts
|
|
271
302
|
|
|
272
303
|
A `z.boolean()` is rarely filled in by hand — its value usually arrives from a spreadsheet column, a CSV
|
|
@@ -282,12 +313,15 @@ booleans `true`/`false` and the numbers `1`/`0`:
|
|
|
282
313
|
So `'YES'`, `' Off '` and `'Enabled'` all work.
|
|
283
314
|
|
|
284
315
|
**Anything else is a validation error, not a guess.** `'maybe'`, `'2'`, `'tr'`, a list or an object each
|
|
285
|
-
fail with `«Field»
|
|
316
|
+
fail with `«Field» must be true or false`. That matters more than the width of the list: a
|
|
286
317
|
conversion that quietly turned an unrecognised value into `false` would read an explicit *on* as *off* and
|
|
287
318
|
never say so.
|
|
288
319
|
|
|
289
320
|
A blank is absence rather than `false` — see [16-gotchas.md](16-gotchas.md).
|
|
290
321
|
|
|
322
|
+
This list applies to **params** only. A vendor's response is never converted: compare a response flag with the
|
|
323
|
+
value the vendor documents — see [16-gotchas.md](16-gotchas.md#conversion-runs-on-the-way-in-never-on-the-way-back).
|
|
324
|
+
|
|
291
325
|
If you need a spelling that is not listed, the test for adding one is that **it has an unambiguous opposite
|
|
292
326
|
and the pair is added together.** A word with no opposite is a status, not a boolean, and belongs in a
|
|
293
327
|
`z.enum([...])`.
|
|
@@ -104,6 +104,10 @@ execute: async ({ params, apiRequest }) => {
|
|
|
104
104
|
The same applies to a list endpoint: return the items **and** the paging fields around them, not a bare
|
|
105
105
|
array. Adding a derived field is fine — spread the response and add to it — but the original fields stay.
|
|
106
106
|
|
|
107
|
+
A response is not converted the way params are: a vendor's `"0"` arrives as the string `"0"`, which is truthy.
|
|
108
|
+
Branch on a response flag by comparing it with the value the vendor documents — see
|
|
109
|
+
[16-gotchas.md](16-gotchas.md#conversion-runs-on-the-way-in-never-on-the-way-back).
|
|
110
|
+
|
|
107
111
|
## `execute` context bag
|
|
108
112
|
|
|
109
113
|
The same bag is passed to actions, dictionaries, triggers, and result-loaders (accessed via arguments,
|
|
@@ -156,6 +156,37 @@ The general rule: when one value is reachable in more than one form, either deri
|
|
|
156
156
|
place, or make the derivation itself idempotent to the difference. This applies to anything `initContext`
|
|
157
157
|
touches — a base URL with or without a trailing slash, an id as a string or a number.
|
|
158
158
|
|
|
159
|
+
## Conversion runs on the way in, never on the way back
|
|
160
|
+
|
|
161
|
+
A `z.boolean()` **param** accepts `yes`, `on`, `1`, `'false'` and the rest of the list in
|
|
162
|
+
[02-zod-types.md](02-zod-types.md#what-a-boolean-accepts). Nothing like that happens to what a **vendor** sends
|
|
163
|
+
back: a response is not declared, so it reaches your code exactly as the API serialized it. A flag sent as the
|
|
164
|
+
string `"0"` is truthy:
|
|
165
|
+
|
|
166
|
+
```js
|
|
167
|
+
note: record.is_active ? 'Active' : 'Archived' // ✗ "0" → 'Active'
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
That shipped as a disconnected device badged *Online*, unverified senders offered as verified, and archived
|
|
171
|
+
projects labelled *Active* — and in a dictionary's `note` or `label` it is a wrong choice made by a person,
|
|
172
|
+
with nothing anywhere to catch it.
|
|
173
|
+
|
|
174
|
+
**Compare the flag strictly against the value the vendor documents**, at the point you branch on it:
|
|
175
|
+
|
|
176
|
+
| The vendor documents | Branch on |
|
|
177
|
+
|---|---|
|
|
178
|
+
| a JSON boolean | `entry.toll_free === true` |
|
|
179
|
+
| `'1'` / `'0'` | `form.is_active === '1'` |
|
|
180
|
+
| `'true'` / `'false'` | `rule.hidden === 'true'` |
|
|
181
|
+
|
|
182
|
+
- **Read the vendor's docs (or a real response) per field** for the form it sends, and test with that form.
|
|
183
|
+
- **Widen only where the vendor really varies** — one endpoint answering `1` and another `"1"`:
|
|
184
|
+
`[1, '1'].includes(entry.active)`. Not a helper that knows ten spellings.
|
|
185
|
+
- **A pass-through is not this trap.** `list.counts.subscribed ?? 0` forwards a value; only a *branch* on a
|
|
186
|
+
flag can invert one.
|
|
187
|
+
- **An input flag is a param, not a response flag.** A flag that reaches you as a param — a criterion, a
|
|
188
|
+
value bound from a template — is declared `z.boolean()`, and the runtime converts it.
|
|
189
|
+
|
|
159
190
|
## A schema slot must be a `z.object`, or the method quietly has no inputs
|
|
160
191
|
|
|
161
192
|
`params`, `criteria` and `configItems` are containers of named fields. Hand one anything else and there is
|
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.
|
|
14511
|
+
version: "0.1.17",
|
|
14512
14512
|
publishConfig: {
|
|
14513
14513
|
access: "public"
|
|
14514
14514
|
},
|
|
@@ -16379,8 +16379,29 @@ function toStringValue(value) {
|
|
|
16379
16379
|
if (typeof value === "boolean") {
|
|
16380
16380
|
return ok(String(value));
|
|
16381
16381
|
}
|
|
16382
|
+
if (value !== null && typeof value === "object") {
|
|
16383
|
+
return ok(value instanceof Date ? value.toISOString() : JSON.stringify(value));
|
|
16384
|
+
}
|
|
16382
16385
|
return typeof value === "number" && Number.isFinite(value) ? ok(String(value)) : fail2("string");
|
|
16383
16386
|
}
|
|
16387
|
+
var OPENS = { array: "[", object: "{" };
|
|
16388
|
+
function parseContainerText(value, kind) {
|
|
16389
|
+
if (typeof value !== "string") {
|
|
16390
|
+
return value;
|
|
16391
|
+
}
|
|
16392
|
+
const text2 = value.trim();
|
|
16393
|
+
if (!text2.startsWith(OPENS[kind])) {
|
|
16394
|
+
return value;
|
|
16395
|
+
}
|
|
16396
|
+
try {
|
|
16397
|
+
const parsed = JSON.parse(text2);
|
|
16398
|
+
const isList = Array.isArray(parsed);
|
|
16399
|
+
const fits = kind === "array" ? isList : parsed !== null && typeof parsed === "object" && !isList;
|
|
16400
|
+
return fits ? parsed : value;
|
|
16401
|
+
} catch {
|
|
16402
|
+
return value;
|
|
16403
|
+
}
|
|
16404
|
+
}
|
|
16384
16405
|
function toNumberValue(value) {
|
|
16385
16406
|
if (typeof value === "number") {
|
|
16386
16407
|
return Number.isFinite(value) ? ok(value) : fail2("number");
|
|
@@ -16463,7 +16484,11 @@ function coerceUnion(value, branches) {
|
|
|
16463
16484
|
if (branches.some((branch) => accepts(branch, value))) {
|
|
16464
16485
|
return value;
|
|
16465
16486
|
}
|
|
16487
|
+
const isStructure = value !== null && typeof value === "object";
|
|
16466
16488
|
for (const branch of branches) {
|
|
16489
|
+
if (isStructure && inspect(branch).coreType === "string") {
|
|
16490
|
+
continue;
|
|
16491
|
+
}
|
|
16467
16492
|
const coerced = coerceDeep(value, branch);
|
|
16468
16493
|
if (accepts(branch, coerced)) {
|
|
16469
16494
|
return coerced;
|
|
@@ -16488,22 +16513,25 @@ function coerceDeep(value, schema) {
|
|
|
16488
16513
|
}
|
|
16489
16514
|
if (ins.coreType === "array") {
|
|
16490
16515
|
const element = ins.core?._zod?.def?.element;
|
|
16491
|
-
|
|
16516
|
+
const list = parseContainerText(value, "array");
|
|
16517
|
+
return Array.isArray(list) ? list.map((item) => coerceDeep(item, element)) : list;
|
|
16492
16518
|
}
|
|
16493
16519
|
if (ins.coreType === "record") {
|
|
16494
|
-
|
|
16495
|
-
|
|
16520
|
+
const map = parseContainerText(value, "object");
|
|
16521
|
+
if (typeof map !== "object" || Array.isArray(map)) {
|
|
16522
|
+
return map;
|
|
16496
16523
|
}
|
|
16497
16524
|
const valueType = ins.core?._zod?.def?.valueType;
|
|
16498
16525
|
return Object.fromEntries(
|
|
16499
|
-
Object.entries(
|
|
16526
|
+
Object.entries(map).map(([key, item]) => [key, coerceDeep(item, valueType)])
|
|
16500
16527
|
);
|
|
16501
16528
|
}
|
|
16502
16529
|
if (ins.coreType === "object") {
|
|
16503
|
-
|
|
16504
|
-
|
|
16530
|
+
const parsed = parseContainerText(value, "object");
|
|
16531
|
+
if (typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
16532
|
+
return parsed;
|
|
16505
16533
|
}
|
|
16506
|
-
const source =
|
|
16534
|
+
const source = parsed;
|
|
16507
16535
|
const coerced = { ...source };
|
|
16508
16536
|
for (const [name, property] of shapeEntries(ins.core)) {
|
|
16509
16537
|
if (name in source) {
|
|
@@ -16616,6 +16644,8 @@ var EXPECTED = {
|
|
|
16616
16644
|
date: "a date",
|
|
16617
16645
|
object: "an object",
|
|
16618
16646
|
array: "an array",
|
|
16647
|
+
// zod's own token for `z.record()`, which the author declared as a map — to a person it is an object.
|
|
16648
|
+
record: "an object",
|
|
16619
16649
|
// `z.json()`. Not a zod token — ./coerce.ts raises it when the submitted text will not parse.
|
|
16620
16650
|
json: "valid JSON"
|
|
16621
16651
|
};
|