@flowrunner/cli 0.1.18 → 0.1.19

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 (28) hide show
  1. package/ai-docs/instructions/service-code-format/02-zod-types.md +115 -7
  2. package/ai-docs/instructions/service-code-format/11-output-model.md +3 -0
  3. package/ai-docs/instructions/service-code-format/16-gotchas.md +30 -6
  4. package/dist/cli.js +625 -48
  5. package/dist/cli.js.map +4 -4
  6. package/dist/index.js +624 -47
  7. package/dist/index.js.map +4 -4
  8. package/dist/types/flow-extension-runner/src/v2/context/execution-context.d.ts +8 -0
  9. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -0
  10. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +2 -0
  11. package/dist/types/flow-extension-runner/src/v2/params/schema/date-format.d.ts +80 -0
  12. package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +3 -2
  13. package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -2
  14. package/dist/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +8 -0
  15. package/dist/types/flow-extension-runner/src/v2/params/schema/notices.d.ts +15 -0
  16. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +21 -0
  17. package/package.json +1 -1
  18. package/runtime/index.js +631 -48
  19. package/runtime/index.js.map +4 -4
  20. package/runtime/types/flow-extension-runner/src/v2/context/execution-context.d.ts +8 -0
  21. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -0
  22. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +2 -0
  23. package/runtime/types/flow-extension-runner/src/v2/params/schema/date-format.d.ts +80 -0
  24. package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +3 -2
  25. package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -2
  26. package/runtime/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +8 -0
  27. package/runtime/types/flow-extension-runner/src/v2/params/schema/notices.d.ts +15 -0
  28. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +21 -0
@@ -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;
@@ -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 {};
@@ -21,8 +21,9 @@ export declare const FORMAT_DESCRIPTIONS: Record<string, string>;
21
21
  * What a field's declaration explains about itself, most specific wins:
22
22
  *
23
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`
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()`, …
26
+ * 4. the plain core type — `number`, `bigint`, `literal`, `enum`, `date`
26
27
  *
27
28
  * Each is read past the optional/nullable/default wrappers, so a modifier never changes the answer.
28
29
  */
@@ -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 {
@@ -16,10 +17,10 @@ export interface FieldPlan {
16
17
  *
17
18
  * Carried because `coreType` alone stops describing the field: a union resolves to its first branch, so a
18
19
  * `z.union([z.email(), z.literal('')])` reports `'string'` and would then treat a blank as a VALUE. It is
19
- * not one — `''` has always been absence on a union, which is exactly what makes the documented
20
- * "blank means not set" spelling (`z.union([z.url(), z.literal('')]).optional()`) work.
20
+ * not one — `''` is absence on a union, unless the union declares it (`blankBranch`).
21
21
  */
22
22
  isUnion: boolean;
23
+ blankBranch: boolean;
23
24
  absence: AbsencePolicy;
24
25
  absorbsBlank: boolean;
25
26
  keepsEmpty: boolean;
@@ -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;
@@ -53,6 +53,14 @@ export interface WidgetInfo {
53
53
  };
54
54
  }
55
55
  export declare function literalType(core: AnyZod): string | undefined;
56
+ /**
57
+ * True when a union declares `''` as one of its forms — a `z.literal('')` branch (FR-3933).
58
+ *
59
+ * On such a union `''` is a VALUE, not a blank: the author listed it, so it is the deliberate "empty" a flow
60
+ * sends (the Empty Text chip, a bound `''`), while `null` and a missing value stay "not provided". That is the
61
+ * only way a flow can clear a date: an untouched block field arrives as `null`, so `null` cannot mean "clear".
62
+ */
63
+ export declare function hasBlankBranch(ins: Inspected): boolean;
56
64
  export declare function deriveWidget(ins: Inspected): WidgetInfo;
57
65
  export declare function shapeEntries(schema: AnyZod | undefined): [name: string, schema: AnyZod][];
58
66
  export declare function fieldLabels(schema: AnyZod): Record<string, string> | undefined;
@@ -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;
@@ -38,6 +38,8 @@ export interface FrMeta {
38
38
  * method that runs it on a decoded one. Never encoded as the spec: see ./json/encode.ts.
39
39
  */
40
40
  frDynamicProps?: DynamicPropsSpec | DynamicPropsRef;
41
+ /** `.dateFormat(pattern)` — the date-fns pattern a date-string field is handed to `execute` in. */
42
+ frDateFormat?: string;
41
43
  }
42
44
  declare module 'zod' {
43
45
  interface ZodType {
@@ -93,6 +95,25 @@ declare module 'zod' {
93
95
  /** Mark the field required — see `ZodUnknown.required`. */
94
96
  required(): this;
95
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
+ }
96
117
  }
97
118
  declare function text(): baseZod.ZodString;
98
119
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flowrunner/cli",
3
- "version": "0.1.18",
3
+ "version": "0.1.19",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },