@flowrunner/cli 0.1.17 → 0.1.18-dev.1
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 +139 -33
- package/ai-docs/instructions/service-code-format/03-parameters.md +3 -1
- package/ai-docs/instructions/service-code-format/05-dictionaries.md +8 -2
- package/ai-docs/instructions/service-code-format/07-actions.md +1 -1
- package/ai-docs/instructions/service-code-format/11-output-model.md +3 -0
- package/ai-docs/instructions/service-code-format/14-reference-service.md +1 -1
- package/ai-docs/instructions/service-code-format/16-gotchas.md +80 -0
- package/ai-docs/instructions/service-code-format/18-test-recipes.md +2 -1
- package/ai-docs/instructions/service-code-format/README.md +1 -1
- package/dist/cli.js +523 -82
- package/dist/cli.js.map +4 -4
- package/dist/index.js +522 -81
- package/dist/index.js.map +4 -4
- package/dist/types/flow-extension-runner/src/v2/context/execution-context.d.ts +8 -0
- package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
- package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/date-format.d.ts +80 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -10
- package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +7 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/notices.d.ts +15 -0
- package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
- package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +30 -19
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -1
- package/package.json +1 -1
- package/runtime/index.js +529 -82
- package/runtime/index.js.map +4 -4
- package/runtime/types/flow-extension-runner/src/v2/context/execution-context.d.ts +8 -0
- package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
- package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/date-format.d.ts +80 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -10
- package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +7 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/notices.d.ts +15 -0
- package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
- package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +30 -19
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -1
|
@@ -8,11 +8,19 @@ export interface ExecutionContextOptions {
|
|
|
8
8
|
accessToken?: string;
|
|
9
9
|
logger?: Logger;
|
|
10
10
|
files?: unknown;
|
|
11
|
+
invocation?: {
|
|
12
|
+
flowId?: string;
|
|
13
|
+
executionId?: string;
|
|
14
|
+
};
|
|
11
15
|
}
|
|
12
16
|
export declare class ExecutionContext {
|
|
13
17
|
#private;
|
|
14
18
|
constructor(extension: Extension, options?: ExecutionContextOptions);
|
|
15
19
|
get logger(): Logger;
|
|
20
|
+
get invocation(): {
|
|
21
|
+
flowId?: string;
|
|
22
|
+
executionId?: string;
|
|
23
|
+
};
|
|
16
24
|
get config(): Record<string, unknown>;
|
|
17
25
|
get oauth(): OAuthBag;
|
|
18
26
|
get filesScope(): FileScopes;
|
|
@@ -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
|
|
7
|
+
search: string;
|
|
8
8
|
cursor?: unknown;
|
|
9
9
|
criteria: Record<string, unknown>;
|
|
10
10
|
}
|
|
@@ -9,8 +9,10 @@ export type { AnyZod, Inspected, WidgetInfo } from './schema/introspect';
|
|
|
9
9
|
export { deriveWidget, fieldLabels, inspect, shapeEntries } from './schema/introspect';
|
|
10
10
|
export { humanizeKey, labelOf } from './schema/labels';
|
|
11
11
|
export { coerceValue } from './schema/coerce';
|
|
12
|
+
export { compilePattern, formatParts, ISO_PATTERNS, parseInPattern } from './schema/date-format';
|
|
12
13
|
export { absenceOf, type AbsencePolicy, type FieldPlan, planField } from './schema/field-plan';
|
|
13
14
|
export { type FieldResult, normalizeField } from './schema/normalize';
|
|
15
|
+
export { collectNotices, type ParamNotice } from './schema/notices';
|
|
14
16
|
export { type FailFn, parseSchema, toIssues } from './schema/parse';
|
|
15
17
|
export { decodeField, decodeParams } from './json/decode';
|
|
16
18
|
export { encodeField, encodeParams, type EncodeParamsOptions } from './json/encode';
|
|
@@ -31,6 +31,7 @@ export interface MetaJSON {
|
|
|
31
31
|
dependsOn: string[];
|
|
32
32
|
};
|
|
33
33
|
frLabels?: Record<string, string>;
|
|
34
|
+
frDateFormat?: string;
|
|
34
35
|
}
|
|
35
36
|
export type FieldType = 'string' | 'number' | 'bigint' | 'boolean' | 'date' | 'enum' | 'literal' | 'object' | 'array' | 'record' | 'union'
|
|
36
37
|
/**
|
|
@@ -45,6 +46,7 @@ export interface FieldJSON {
|
|
|
45
46
|
name: string;
|
|
46
47
|
type: FieldType;
|
|
47
48
|
format?: string;
|
|
49
|
+
local?: true;
|
|
48
50
|
optional?: true;
|
|
49
51
|
nullable?: true;
|
|
50
52
|
default?: JsonValue;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { type AnyZod, type Inspected } from './introspect';
|
|
2
|
+
export type DateStringKind = 'date' | 'datetime' | 'time';
|
|
3
|
+
export declare const ISO_PATTERNS: Record<DateStringKind, string>;
|
|
4
|
+
/**
|
|
5
|
+
* ⚠️ TEMPORARY (FR-3920 lenient period). A flow saved before a service moved from `z.date()` to a string type
|
|
6
|
+
* holds a TIMESTAMP — epoch millis, the old picker's value. While this is true, such a timestamp is still
|
|
7
|
+
* accepted: read in the server's time zone, put into the declared pattern, and logged as a warning per
|
|
8
|
+
* conversion so the flows still holding one can be found.
|
|
9
|
+
*
|
|
10
|
+
* The next release flips it to `false` (a timestamp is refused, as the string types intend), once the
|
|
11
|
+
* warnings stop. Only a timestamp is affected — every other input follows the strict rules either way.
|
|
12
|
+
*/
|
|
13
|
+
export declare const DATE_STRINGS_ACCEPT_TIMESTAMPS = true;
|
|
14
|
+
export interface DateParts {
|
|
15
|
+
year?: number;
|
|
16
|
+
month?: number;
|
|
17
|
+
day?: number;
|
|
18
|
+
hour?: number;
|
|
19
|
+
minute?: number;
|
|
20
|
+
second?: number;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Which date-string kind a field is, or `undefined` when it is not one.
|
|
24
|
+
*
|
|
25
|
+
* `z.iso.datetime()` WITHOUT `local: true` is an instant — it has a zone — and is not a date string: it
|
|
26
|
+
* keeps its own conversion in ./dates.ts.
|
|
27
|
+
*/
|
|
28
|
+
export declare function dateStringKind(ins: Inspected): DateStringKind | undefined;
|
|
29
|
+
/** The pattern a date-string field hands to `execute`: the declared one, or the ISO one. */
|
|
30
|
+
export declare const patternOf: (ins: Inspected, kind: DateStringKind) => string;
|
|
31
|
+
type TokenName = 'yyyy' | 'yy' | 'MM' | 'M' | 'dd' | 'd' | 'HH' | 'H' | 'hh' | 'h' | 'mm' | 'ss' | 'a';
|
|
32
|
+
type Token = {
|
|
33
|
+
token: TokenName;
|
|
34
|
+
} | {
|
|
35
|
+
literal: string;
|
|
36
|
+
};
|
|
37
|
+
/** A pattern the runner cannot use. The message completes "`.dateFormat('…')` …". */
|
|
38
|
+
export declare class DateFormatError extends Error {
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Check `pattern` for `kind` and return its tokens. Throws `DateFormatError` with a message naming the
|
|
42
|
+
* problem and, where it can, the pattern the author meant.
|
|
43
|
+
*/
|
|
44
|
+
export declare function compilePattern(pattern: string, kind: DateStringKind): Token[];
|
|
45
|
+
/** The parts as text in `pattern`. The parts are assumed valid — they come from `parse*` below. */
|
|
46
|
+
export declare function formatParts(parts: DateParts, pattern: string, kind: DateStringKind): string;
|
|
47
|
+
/**
|
|
48
|
+
* `text` read STRICTLY in `pattern`: it must be exactly what formatting its own parts produces. That one
|
|
49
|
+
* rule refuses `1/2/2024` for `dd/MM/yyyy`, `31/02/2024`, `24:00` and `pm` for `PM` — and it is the rule the
|
|
50
|
+
* console's picker applies too, so the picker never commits a string the runner then refuses.
|
|
51
|
+
*/
|
|
52
|
+
export declare function parseInPattern(text: string, pattern: string, kind: DateStringKind): DateParts | undefined;
|
|
53
|
+
/** An ISO string → the parts `kind` needs, or `undefined` when it does not carry them. */
|
|
54
|
+
export declare function parseIso(text: string, kind: DateStringKind): DateParts | undefined;
|
|
55
|
+
/** The parts as canonical ISO — what zod's check on the type accepts, and what the pipeline carries. */
|
|
56
|
+
export declare function toCanonical(parts: DateParts, kind: DateStringKind): string;
|
|
57
|
+
/**
|
|
58
|
+
* The canonical ISO text, written out in the declared pattern. Without a declared pattern it is returned as
|
|
59
|
+
* it is: canonical ISO is the ISO form, and keeps the seconds the input had.
|
|
60
|
+
*/
|
|
61
|
+
export declare function canonicalToPattern(canonical: string, ins: Inspected, kind: DateStringKind): string;
|
|
62
|
+
export interface DateStringResult {
|
|
63
|
+
canonical?: string;
|
|
64
|
+
fromTimestamp?: boolean;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Any input → canonical ISO for a date-string field, in this order:
|
|
68
|
+
*
|
|
69
|
+
* 1. text in the DECLARED pattern, read strictly — first, so `yyyy-dd-MM` reads `2024-05-06` as 5 June;
|
|
70
|
+
* 2. an ISO date / date-time / time, read lexically (the zone dropped, nothing widened);
|
|
71
|
+
* 3. a timestamp — only during the lenient period, read in the server's zone.
|
|
72
|
+
*
|
|
73
|
+
* Anything else is not a date of this kind.
|
|
74
|
+
*/
|
|
75
|
+
export declare function toDateString(value: unknown, ins: Inspected, kind: DateStringKind): DateStringResult;
|
|
76
|
+
/** "a date in dd/MM/yyyy, e.g. 31/01/2024" — completes "«Label» must be …". */
|
|
77
|
+
export declare function expectedDateString(ins: Inspected, kind: DateStringKind): string;
|
|
78
|
+
/** Whether `.dateFormat()` sits anywhere in `schema` — the field, a property, a list item, a union branch. */
|
|
79
|
+
export declare function hasDateFormat(schema: AnyZod | undefined, seen?: Set<unknown>): boolean;
|
|
80
|
+
export {};
|
|
@@ -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,11 @@ 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.
|
|
30
|
-
* 2. a
|
|
31
|
-
* 3. a zod `format` token — `z.email()`, `z.ipv4()`, `z.iso.
|
|
23
|
+
* 1. a FlowRunner widget marker — `z.text()`, a string the console renders specially
|
|
24
|
+
* 2. a date or time as text — `z.iso.date().dateFormat('dd/MM/yyyy')`: the pattern and an example
|
|
25
|
+
* 3. a zod `format` token — `z.email()`, `z.ipv4()`, `z.iso.datetime()`, …
|
|
32
26
|
* 4. the plain core type — `number`, `bigint`, `literal`, `enum`, `date`
|
|
33
27
|
*
|
|
34
|
-
*
|
|
28
|
+
* Each is read past the optional/nullable/default wrappers, so a modifier never changes the answer.
|
|
35
29
|
*/
|
|
36
30
|
export declare function describeField(schema: AnyZod): string | undefined;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type DateStringKind } from './date-format';
|
|
1
2
|
import { type AnyZod } from './introspect';
|
|
2
3
|
export type AbsencePolicy = 'as-received' | 'undefined' | 'null' | 'required';
|
|
3
4
|
export interface Absence {
|
|
@@ -32,6 +33,12 @@ export interface FieldPlan {
|
|
|
32
33
|
*/
|
|
33
34
|
passThroughDate: boolean;
|
|
34
35
|
restoresDates: boolean;
|
|
36
|
+
/**
|
|
37
|
+
* The field ITSELF is a date or time as text (FR-3920): `z.iso.date()`, `z.iso.datetime({ local: true })`,
|
|
38
|
+
* `z.iso.time()`. Its core type is `string`, but `''` is absence on it, as on every type with no empty value.
|
|
39
|
+
*/
|
|
40
|
+
dateString?: DateStringKind;
|
|
41
|
+
formatsDates: boolean;
|
|
35
42
|
}
|
|
36
43
|
/** The absent forms a schema accepts, at any depth. Same question `planField` asks for a top-level field. */
|
|
37
44
|
export declare function absenceOf(schema: AnyZod | undefined): Absence;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export interface ParamNotice {
|
|
2
|
+
field?: string;
|
|
3
|
+
message: string;
|
|
4
|
+
value: unknown;
|
|
5
|
+
converted: string;
|
|
6
|
+
}
|
|
7
|
+
/** Run `fn`, returning what it returned and every notice raised while it ran. Nests: the inner one collects. */
|
|
8
|
+
export declare function collectNotices<T>(fn: () => T): {
|
|
9
|
+
result: T;
|
|
10
|
+
notices: ParamNotice[];
|
|
11
|
+
};
|
|
12
|
+
/** Run `fn` with notices attributed to `field`. */
|
|
13
|
+
export declare function withinField<T>(field: string, fn: () => T): T;
|
|
14
|
+
/** Raise a notice. Without an open collector — a console form, a test — it goes nowhere. */
|
|
15
|
+
export declare function notice(entry: Omit<ParamNotice, 'field'>): void;
|
|
@@ -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()
|
|
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,13 +33,13 @@ 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.
|
|
41
39
|
*/
|
|
42
40
|
frDynamicProps?: DynamicPropsSpec | DynamicPropsRef;
|
|
41
|
+
/** `.dateFormat(pattern)` — the date-fns pattern a date-string field is handed to `execute` in. */
|
|
42
|
+
frDateFormat?: string;
|
|
43
43
|
}
|
|
44
44
|
declare module 'zod' {
|
|
45
45
|
interface ZodType {
|
|
@@ -95,28 +95,39 @@ declare module 'zod' {
|
|
|
95
95
|
/** Mark the field required — see `ZodUnknown.required`. */
|
|
96
96
|
required(): this;
|
|
97
97
|
}
|
|
98
|
+
interface ZodISODate {
|
|
99
|
+
/**
|
|
100
|
+
* The text `execute` receives, as a date-fns pattern: `z.iso.date().dateFormat('dd/MM/yyyy')` → `'31/01/2024'`.
|
|
101
|
+
* Without it the value is ISO (`2024-01-31`, `2024-01-31T13:45`, `13:45`). Tokens: yyyy yy MM M dd d HH H
|
|
102
|
+
* hh h mm ss a, and literal text in single quotes. Checked when the service loads.
|
|
103
|
+
*
|
|
104
|
+
* Not `.format()`: zod 4 keeps `format` as an own STRING property on every string schema
|
|
105
|
+
* (`z.iso.date().format === 'date'`), which shadows a prototype method and is restored on every clone.
|
|
106
|
+
*/
|
|
107
|
+
dateFormat(pattern: string): this;
|
|
108
|
+
}
|
|
109
|
+
interface ZodISODateTime {
|
|
110
|
+
/** See `ZodISODate.dateFormat`. Only with `{ local: true }` — checked when the service loads. */
|
|
111
|
+
dateFormat(pattern: string): this;
|
|
112
|
+
}
|
|
113
|
+
interface ZodISOTime {
|
|
114
|
+
/** See `ZodISODate.dateFormat`. */
|
|
115
|
+
dateFormat(pattern: string): this;
|
|
116
|
+
}
|
|
98
117
|
}
|
|
99
118
|
declare function text(): baseZod.ZodString;
|
|
100
119
|
/**
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
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`.
|
|
120
|
+
* `z.json()` is not a param type. It was one — JSON typed into a textarea, parsed before the handler ran — and
|
|
121
|
+
* was removed (FR-3910): `z.unknown()` takes any value as given, and a declared `z.object()` / `z.array()` takes
|
|
122
|
+
* JSON text of its kind (see ./schema/coerce.ts), so the only thing it still offered was a parse of free text
|
|
123
|
+
* into a value nobody had described.
|
|
114
124
|
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
* the extension never registers (FR-3600). An author
|
|
125
|
+
* It throws rather than disappearing, because the name would otherwise fall through to zod's own `z.json()`
|
|
126
|
+
* (the namespace is `Object.create(baseZod)`), which cannot be declared at all: it recurses until the stack is
|
|
127
|
+
* gone and the extension never registers (FR-3600). An author following an old example gets a message naming
|
|
128
|
+
* what to write instead, at registration, instead of a stack overflow.
|
|
118
129
|
*/
|
|
119
|
-
declare function json():
|
|
130
|
+
declare function json(): never;
|
|
120
131
|
export declare const z: Omit<typeof baseZod, "json"> & {
|
|
121
132
|
text: typeof text;
|
|
122
133
|
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
|
|
93
|
+
search: string;
|
|
94
94
|
cursor?: unknown;
|
|
95
95
|
criteria: Infer<TCriteria>;
|
|
96
96
|
}) => DictionaryResult | DictionaryResultItems | Promise<DictionaryResult | DictionaryResultItems>;
|