@lowdefy/node-utils 0.0.0-experimental-20261006165558 → 0.0.0-experimental-20261007124348

package/dist/createConnectPublic.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { isIP } from 'node:net';
+import { buildConnector } from 'undici';
+import createLookupPublicAddress from './createLookupPublicAddress.js';
+// An undici connector that opens a socket only to a public address, for the first link and every
+// redirect alike. A socket to an IP literal skips the lookup, so a literal is checked here before
+// connecting. A refused address fails the connection with the error createNotPublicError(hostname)
+// returns.
+function createConnectPublic({ createNotPublicError }) {
+    const lookupPublicAddress = createLookupPublicAddress({
+        createNotPublicError
+    });
+    const connect = buildConnector({
+        lookup: lookupPublicAddress
+    });
+    return function connectPublic(options, callback) {
+        if (isIP(options.hostname) === 0) {
+            connect(options, callback);
+            return;
+        }
+        lookupPublicAddress(options.hostname, {
+            all: true
+        }, (error)=>{
+            if (error) {
+                callback(error, null);
+                return;
+            }
+            connect(options, callback);
+        });
+    };
+}
+export default createConnectPublic;

package/dist/createLookupPublicAddress.js

@@ -0,0 +1,39 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { lookup } from 'node:dns';
+import isPublicAddress from './isPublicAddress.js';
+// A dns.lookup for the socket to use: the socket connects to the addresses this answers, so the
+// address checked is the address connected to, and a name that resolves differently on a second
+// lookup cannot get past the check. Refuses a name when any of its addresses is not public, with
+// the error createNotPublicError(hostname) returns.
+function createLookupPublicAddress({ createNotPublicError }) {
+    return function lookupPublicAddress(hostname, options, callback) {
+        lookup(hostname, options, (error, address, family)=>{
+            if (error) {
+                callback(error);
+                return;
+            }
+            const addresses = Array.isArray(address) ? address.map((entry)=>entry.address) : [
+                address
+            ];
+            if (!addresses.every(isPublicAddress)) {
+                callback(createNotPublicError(hostname));
+                return;
+            }
+            callback(null, address, family);
+        });
+    };
+}
+export default createLookupPublicAddress;

package/dist/index.js

@@ -18,7 +18,9 @@ import cleanDirectory from './cleanDirectory.js';
 import collectEnvironmentGuards from './collectEnvironmentGuards.js';
 import compareProcessStartTimes from './compareProcessStartTimes.js';
 import copyFileOrDirectory from './copyFileOrDirectory.js';
+import createConnectPublic from './createConnectPublic.js';
 import createClientAddressResolver from './createClientAddressResolver.js';
+import createLookupPublicAddress from './createLookupPublicAddress.js';
 import createSecretScrubber from './createSecretScrubber.js';
 import devPassiveHeader from './devPassiveHeader.js';
 import dataSetNamePattern from './dataSetNamePattern.js';
@@ -33,6 +35,7 @@ import getSecretsFromEnv from './getSecretsFromEnv.js';
 import installIfPackageJsonChanged from './installIfPackageJsonChanged.js';
 import isPidAlive from './isPidAlive.js';
 import isProcessAlive from './isProcessAlive.js';
+import isPublicAddress from './isPublicAddress.js';
 import isProcessStartTime from './isProcessStartTime.js';
 import isPortAvailable from './isPortAvailable.js';
 import linkDependenciesToWorkspace from './linkDependenciesToWorkspace.js';
@@ -64,6 +67,8 @@ import findPlaceholderStep from './journeyGrammar/findPlaceholderStep.js';
 import failurePathKey from './journeyEvidence/failurePathKey.js';
 import isBackedBy from './journeyEvidence/isBackedBy.js';
 import normaliseBlockId from './journeyGrammar/normaliseBlockId.js';
+import normaliseJourneySteps from './journeyGrammar/normaliseJourneySteps.js';
+import journeyStepSchema, { JOURNEY_STEP_SCHEMAS } from './journeyGrammar/journeyStepSchema.js';
 import hashSequence from './journeyCompiler/hashSequence.js';
 import journeySequence from './journeyCompiler/journeySequence.js';
 import listFailurePaths from './journeyCompiler/listFailurePaths.js';
@@ -78,4 +83,4 @@ import validateJourneySteps, { getStepKey, INTERACTION_STEP_KEYS, STEP_KEYS, TAR
 import validateJourneyTags, { JOURNEY_TAG_PATTERN } from './journeyGrammar/validateJourneyTags.js';
 import validateJourneyUser from './journeyGrammar/validateJourneyUser.js';
 import validateTraceRecord from './journeyTrace/validateTraceRecord.js';
-export { acquireMachineSlot, buildSessionReport, checkEnvironmentGuards, cleanDirectory, collectEnvironmentGuards, compareProcessStartTimes, compileSegments, copyFileOrDirectory, countDataSetDocuments, countTextTokens, createClientAddressResolver, createSecretScrubber, devPassiveHeader, dataSetNamePattern, failurePathKey, findAvailablePort, findPlaceholderStep, findPnpmWorkspaceRoot, formatSessionLog, formatSessionReport, findWorkspacePackages, getDevInstancePath, getFileExtension, getFileSubExtension, getLowdefyHome, getProcessStartTime, getSecretsFromEnv, hashSequence, installIfPackageJsonChanged, isBackedBy, isPidAlive, isProcessAlive, isProcessStartTime, isPortAvailable, journeySequence, linkDependenciesToWorkspace, linkWorkspaceDependencies, listDataSets, parseDataSet, listFailurePaths, listRecordingFiles, matchPagePath, normaliseBlockId, normaliseClickText, parseIpRange, parseSince, parsePsStartTime, parseTraceLines, profileProduction, readDevInstance, readDevInstanceAsync, readProcessStartTime, readServerRegistry, registerServer, readRecordings, RECORDING_SOURCES, spawnProcess, stepIdentity, summariseSessions, readFile, writeFile, writeFileAtomic, watchOwner, writeFileIfChanged, getStepKey, INTERACTION_STEP_KEYS, STEP_KEYS, TARGET_KEYS, validateJourneySteps, validateTraceRecord, JOURNEY_TAG_PATTERN, validateJourneyTags, validateJourneyUser };
+export { acquireMachineSlot, buildSessionReport, checkEnvironmentGuards, cleanDirectory, collectEnvironmentGuards, compareProcessStartTimes, compileSegments, copyFileOrDirectory, countDataSetDocuments, countTextTokens, createClientAddressResolver, createConnectPublic, createLookupPublicAddress, createSecretScrubber, devPassiveHeader, dataSetNamePattern, failurePathKey, findAvailablePort, findPlaceholderStep, findPnpmWorkspaceRoot, formatSessionLog, formatSessionReport, findWorkspacePackages, getDevInstancePath, getFileExtension, getFileSubExtension, getLowdefyHome, getProcessStartTime, getSecretsFromEnv, hashSequence, installIfPackageJsonChanged, isBackedBy, isPidAlive, isProcessAlive, isPublicAddress, isProcessStartTime, isPortAvailable, journeySequence, journeyStepSchema, linkDependenciesToWorkspace, linkWorkspaceDependencies, listDataSets, parseDataSet, listFailurePaths, listRecordingFiles, matchPagePath, normaliseBlockId, normaliseJourneySteps, normaliseClickText, parseIpRange, parseSince, parsePsStartTime, parseTraceLines, profileProduction, readDevInstance, readDevInstanceAsync, readProcessStartTime, readServerRegistry, registerServer, readRecordings, RECORDING_SOURCES, spawnProcess, stepIdentity, summariseSessions, readFile, writeFile, writeFileAtomic, watchOwner, writeFileIfChanged, getStepKey, INTERACTION_STEP_KEYS, JOURNEY_STEP_SCHEMAS, STEP_KEYS, TARGET_KEYS, validateJourneySteps, validateTraceRecord, JOURNEY_TAG_PATTERN, validateJourneyTags, validateJourneyUser };

package/dist/isPublicAddress.js

@@ -0,0 +1,107 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { BlockList, isIPv6 } from 'node:net';
+// Ranges a server-side fetch of a user-supplied link may not reach: anything that is not a public
+// unicast address. BlockList also matches an IPv4-mapped IPv6 address (::ffff:127.0.0.1) against
+// the IPv4 ranges.
+const notPublicIPv4 = [
+    [
+        '0.0.0.0',
+        8
+    ],
+    [
+        '10.0.0.0',
+        8
+    ],
+    [
+        '100.64.0.0',
+        10
+    ],
+    [
+        '127.0.0.0',
+        8
+    ],
+    [
+        '169.254.0.0',
+        16
+    ],
+    [
+        '172.16.0.0',
+        12
+    ],
+    [
+        '192.0.0.0',
+        24
+    ],
+    [
+        '192.168.0.0',
+        16
+    ],
+    [
+        '198.18.0.0',
+        15
+    ],
+    [
+        '224.0.0.0',
+        4
+    ],
+    [
+        '240.0.0.0',
+        4
+    ]
+];
+// The 6to4 address (2002::/16) that carries an IPv4 network in its next 32 bits.
+function sixToFourNetwork(network) {
+    const [a, b, c, d] = network.split('.').map(Number);
+    return `2002:${(a << 8 | b).toString(16)}:${(c << 8 | d).toString(16)}::`;
+}
+const notPublic = new BlockList();
+notPublicIPv4.forEach(([network, prefix])=>{
+    notPublic.addSubnet(network, prefix, 'ipv4');
+    // An IPv6 address that embeds one of these IPv4 addresses: a NAT64 gateway (64:ff9b::/96)
+    // or a 6to4 relay forwards it to that IPv4 address.
+    notPublic.addSubnet(`64:ff9b::${network}`, 96 + prefix, 'ipv6');
+    notPublic.addSubnet(sixToFourNetwork(network), 16 + prefix, 'ipv6');
+});
+[
+    [
+        '::',
+        96
+    ],
+    [
+        '64:ff9b:1::',
+        48
+    ],
+    [
+        'fc00::',
+        7
+    ],
+    [
+        'fe80::',
+        10
+    ],
+    [
+        'fec0::',
+        10
+    ],
+    [
+        'ff00::',
+        8
+    ]
+].forEach(([network, prefix])=>notPublic.addSubnet(network, prefix, 'ipv6'));
+function isPublicAddress(address) {
+    return !notPublic.check(address, isIPv6(address) ? 'ipv6' : 'ipv4');
+}
+export default isPublicAddress;

package/dist/journeyGrammar/journeyStepExamples.js

@@ -0,0 +1,219 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // Well-formed steps, keyed by step and by expect kind. A step error ends with
+// the examples for its step, so an agent that wrote a step wrong gets the
+// right form back; the journey step schema carries the same examples.
+const JOURNEY_STEP_EXAMPLES = {
+    click: [
+        {
+            click: 'save_button'
+        },
+        {
+            click: {
+                text: 'OK'
+            }
+        }
+    ],
+    open: [
+        {
+            open: 'status_selector'
+        }
+    ],
+    fill: [
+        {
+            fill: {
+                blockId: 'name_input',
+                value: 'Ada'
+            }
+        },
+        {
+            fill: {
+                blockId: 'code_input',
+                fromEmail: {
+                    to: 'ada@example.com',
+                    match: '\\d{6}'
+                }
+            }
+        }
+    ],
+    select: [
+        {
+            select: {
+                blockId: 'status_selector',
+                value: 'Open'
+            }
+        }
+    ],
+    press: [
+        {
+            press: 'Enter'
+        }
+    ],
+    back: [
+        {
+            back: true
+        }
+    ],
+    goto: [
+        {
+            goto: 'dashboard'
+        },
+        {
+            goto: {
+                pageId: 'ticket',
+                pathParams: {
+                    ticket_id: '1234'
+                },
+                urlQuery: {
+                    tab: 'notes'
+                }
+            }
+        }
+    ],
+    email: [
+        {
+            email: {
+                to: 'ada@example.com',
+                subject: 'Verify'
+            }
+        }
+    ],
+    as: [
+        {
+            as: 'invitee'
+        }
+    ],
+    wait: [
+        {
+            wait: {
+                request: 'get_orders'
+            }
+        },
+        {
+            wait: {
+                state: 'orders'
+            }
+        },
+        {
+            wait: {
+                ms: 500
+            }
+        }
+    ],
+    screenshot: [
+        {
+            screenshot: 'after_save'
+        }
+    ],
+    expect: [
+        {
+            expect: {
+                visible: 'save_button'
+            }
+        },
+        {
+            expect: {
+                url: {
+                    contains: '/orders'
+                }
+            }
+        }
+    ],
+    'expect.state': [
+        {
+            expect: {
+                state: {
+                    path: 'order.status',
+                    equals: 'Open'
+                }
+            }
+        }
+    ],
+    'expect.visible': [
+        {
+            expect: {
+                visible: 'save_button'
+            }
+        }
+    ],
+    'expect.hidden': [
+        {
+            expect: {
+                hidden: 'error_alert'
+            }
+        }
+    ],
+    'expect.text': [
+        {
+            expect: {
+                text: {
+                    blockId: 'title',
+                    contains: 'Orders'
+                }
+            }
+        }
+    ],
+    'expect.url': [
+        {
+            expect: {
+                url: {
+                    contains: '/orders'
+                }
+            }
+        }
+    ],
+    'expect.title': [
+        {
+            expect: {
+                title: {
+                    contains: 'Orders'
+                }
+            }
+        }
+    ],
+    'expect.calls': [
+        {
+            expect: {
+                calls: {
+                    request: 'save_order',
+                    count: 1
+                }
+            }
+        },
+        {
+            expect: {
+                calls: {
+                    endpoint: 'orders-sync',
+                    count: 1
+                }
+            }
+        }
+    ],
+    'expect.error': [
+        {
+            expect: {
+                error: 'is required'
+            }
+        }
+    ],
+    'expect.effect': [
+        {
+            expect: {
+                effect: true
+            }
+        }
+    ]
+};
+export default JOURNEY_STEP_EXAMPLES;

package/dist/journeyGrammar/journeyStepSchema.js

@@ -0,0 +1,444 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import JOURNEY_STEP_EXAMPLES from './journeyStepExamples.js';
+// The journey step grammar as a JSON schema, for agents to read. The grammar
+// itself is validateJourneySteps; its tests check this schema accepts and
+// refuses the same steps. Rules across steps (expect.error and expect.effect
+// directly follow an interaction) and a fromEmail match being a valid regular
+// expression are checked by the validator only.
+const nonEmptyString = {
+    type: 'string',
+    minLength: 1
+};
+const index = {
+    type: 'integer',
+    minimum: 0
+};
+const FROM = {
+    enum: [
+        'recorded',
+        'shape'
+    ],
+    description: 'Where the value came from: "recorded" (observed in a trace) or "shape" (value: null, a placeholder the runner refuses until it is filled in).'
+};
+const TARGET_PROPERTIES = {
+    blockId: {
+        type: 'string',
+        description: "Scopes the target to the block's wrapper."
+    },
+    text: {
+        type: 'string',
+        description: 'Exact text of the interactive control to use. Without blockId it searches the whole page, which reaches confirm dialog buttons, modal footers, dropdown menu items and email links.'
+    },
+    containing: {
+        ...nonEmptyString,
+        description: 'Text the element shows, e.g. the email address a list row shows.'
+    },
+    row: {
+        ...index,
+        description: 'Zero-based grid row, as displayed. Needs blockId.'
+    },
+    column: {
+        type: 'string',
+        description: 'Grid column id. Needs blockId.'
+    },
+    nth: {
+        ...index,
+        description: 'Zero-based pick among several matches.'
+    }
+};
+function targetObject({ properties = {}, required = [], requireBlockId = false }) {
+    const schema = {
+        type: 'object',
+        properties: {
+            ...TARGET_PROPERTIES,
+            ...properties
+        },
+        additionalProperties: false,
+        required,
+        not: {
+            required: [
+                'text',
+                'containing'
+            ]
+        },
+        dependencies: {
+            row: [
+                'blockId'
+            ],
+            column: [
+                'blockId'
+            ]
+        }
+    };
+    if (requireBlockId) {
+        schema.required = [
+            'blockId',
+            ...required
+        ];
+    } else {
+        schema.anyOf = [
+            {
+                required: [
+                    'blockId'
+                ]
+            },
+            {
+                required: [
+                    'text'
+                ]
+            },
+            {
+                required: [
+                    'containing'
+                ]
+            }
+        ];
+    }
+    return schema;
+}
+const TARGET = {
+    description: 'A blockId string, or a target object.',
+    oneOf: [
+        {
+            type: 'string'
+        },
+        targetObject({})
+    ]
+};
+// A null value is a placeholder, so it must be marked from: shape.
+const VALUE_PLACEHOLDER_RULE = {
+    if: {
+        properties: {
+            value: {
+                type: 'null'
+            }
+        },
+        required: [
+            'value'
+        ]
+    },
+    then: {
+        properties: {
+            from: {
+                const: 'shape'
+            }
+        },
+        required: [
+            'from'
+        ]
+    }
+};
+const FROM_EMAIL = {
+    type: 'object',
+    description: 'Type text read from the newest email to "to": the first match of the regular expression "match", or its first capture group.',
+    properties: {
+        to: nonEmptyString,
+        subject: {
+            type: 'string'
+        },
+        match: {
+            ...nonEmptyString,
+            description: 'A regular expression, e.g. "\\\\b\\\\d{6}\\\\b".'
+        }
+    },
+    required: [
+        'to',
+        'match'
+    ],
+    additionalProperties: false
+};
+function valueTarget() {
+    return {
+        ...targetObject({
+            properties: {
+                value: {},
+                from: FROM
+            },
+            required: [
+                'value'
+            ],
+            requireBlockId: true
+        }),
+        ...VALUE_PLACEHOLDER_RULE
+    };
+}
+function singleKey(properties) {
+    return Object.entries(properties).map(([key, value])=>({
+            type: 'object',
+            properties: {
+                [key]: value
+            },
+            required: [
+                key
+            ],
+            additionalProperties: false
+        }));
+}
+const EXPECT_KINDS = {
+    state: {
+        type: 'object',
+        description: 'State at "path" deep-equals "equals".',
+        properties: {
+            path: {
+                type: 'string'
+            },
+            equals: {},
+            from: FROM
+        },
+        required: [
+            'path',
+            'equals'
+        ],
+        additionalProperties: false
+    },
+    visible: TARGET,
+    hidden: {
+        ...TARGET,
+        description: 'Nothing the target names is visible. Passes at once when nothing matches yet, so pair it with something that must be present first.'
+    },
+    text: targetObject({
+        properties: {
+            contains: {
+                type: 'string'
+            }
+        },
+        required: [
+            'contains'
+        ],
+        requireBlockId: true
+    }),
+    url: {
+        type: 'object',
+        properties: {
+            contains: {
+                type: 'string'
+            }
+        },
+        required: [
+            'contains'
+        ]
+    },
+    title: {
+        description: 'The document title.',
+        oneOf: singleKey({
+            equals: {
+                type: 'string'
+            },
+            contains: {
+                type: 'string'
+            }
+        })
+    },
+    calls: {
+        description: 'How many times this actor called the request (on pageId, default the current page) or the endpoint since the journey started.',
+        oneOf: [
+            {
+                type: 'object',
+                properties: {
+                    request: nonEmptyString,
+                    pageId: nonEmptyString,
+                    count: index
+                },
+                required: [
+                    'request',
+                    'count'
+                ],
+                additionalProperties: false
+            },
+            {
+                type: 'object',
+                properties: {
+                    endpoint: nonEmptyString,
+                    count: index
+                },
+                required: [
+                    'endpoint',
+                    'count'
+                ],
+                additionalProperties: false
+            }
+        ]
+    },
+    error: {
+        ...nonEmptyString,
+        description: 'Text an app error raised by the interaction step directly before this one contains.'
+    },
+    effect: {
+        const: true,
+        description: 'Fails when the interaction step directly before this one did nothing: no event ran, the page did not change, no request or endpoint was called and the URL stayed the same.'
+    }
+};
+const STEPS = {
+    click: {
+        description: 'Click a target. "count": 2 or 3 clicks in quick succession, a double click.',
+        oneOf: [
+            {
+                type: 'string'
+            },
+            targetObject({
+                properties: {
+                    count: {
+                        type: 'integer',
+                        minimum: 1,
+                        maximum: 3
+                    }
+                }
+            })
+        ]
+    },
+    open: {
+        ...TARGET,
+        description: "Open an input's dropdown or picker popup and wait for it to show, so a following screenshot captures it."
+    },
+    fill: {
+        description: 'Type a value into a block, or text read from an email.',
+        oneOf: [
+            valueTarget(),
+            targetObject({
+                properties: {
+                    fromEmail: FROM_EMAIL
+                },
+                required: [
+                    'fromEmail'
+                ],
+                requireBlockId: true
+            })
+        ]
+    },
+    select: {
+        ...valueTarget(),
+        description: 'Pick an option by exact text: a dropdown option, or a radio, button or segmented option in the block.'
+    },
+    press: {
+        type: 'string',
+        description: 'A key, e.g. "Enter" or "Mod+k" (Mod is Meta or Control per platform).'
+    },
+    back: {
+        enum: [
+            true,
+            null
+        ],
+        description: 'The browser Back button.'
+    },
+    goto: {
+        description: 'Load an app page like a typed URL.',
+        oneOf: [
+            nonEmptyString,
+            {
+                type: 'object',
+                properties: {
+                    pageId: nonEmptyString,
+                    pathParams: {
+                        type: 'object',
+                        additionalProperties: {
+                            type: 'string'
+                        },
+                        description: "One string per placeholder of the page's path."
+                    },
+                    urlQuery: {
+                        type: 'object'
+                    }
+                },
+                required: [
+                    'pageId'
+                ],
+                additionalProperties: false
+            }
+        ]
+    },
+    email: {
+        type: 'object',
+        description: 'Open the newest email to "to" that arrived during this journey, subject containing the text, waiting for it if needed.',
+        properties: {
+            to: nonEmptyString,
+            subject: {
+                type: 'string'
+            }
+        },
+        required: [
+            'to'
+        ],
+        additionalProperties: false
+    },
+    as: {
+        ...nonEmptyString,
+        description: 'Switch to another person, with their own browser and cookies. The journey starts as "main".'
+    },
+    wait: {
+        description: 'Wait for a request started since the last interaction to finish, or for a state path to be defined. { ms } (or a bare number of ms) waits a fixed time, which the lowdefy test lint refuses (L3): prefer a request, a state or an expect.',
+        oneOf: [
+            {
+                type: 'number'
+            },
+            ...singleKey({
+                ms: {
+                    type: 'number'
+                },
+                request: {
+                    type: 'string'
+                },
+                state: {
+                    type: 'string'
+                }
+            })
+        ]
+    },
+    screenshot: {
+        description: 'Capture the page, with an optional name.',
+        anyOf: [
+            {
+                type: 'string'
+            },
+            {
+                enum: [
+                    true,
+                    null
+                ]
+            }
+        ]
+    },
+    expect: {
+        description: 'Assert one thing about the page. Each waits until it holds or the step times out.',
+        oneOf: singleKey(EXPECT_KINDS)
+    }
+};
+function stepSchema(key) {
+    return {
+        type: 'object',
+        properties: {
+            [key]: {
+                ...STEPS[key],
+                examples: JOURNEY_STEP_EXAMPLES[key]
+            }
+        },
+        required: [
+            key
+        ],
+        additionalProperties: false
+    };
+}
+const JOURNEY_STEP_SCHEMAS = Object.fromEntries(Object.keys(STEPS).map((key)=>[
+        key,
+        stepSchema(key)
+    ]));
+const journeyStepSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'Journey step',
+    description: 'One step of a journey: an object with exactly one key, the step name. A target is a blockId string or an object of { blockId, text, containing, row, column, nth }; fill, select and expect.text need a blockId. expect.error and expect.effect must directly follow an interaction step (click, open, fill, select, press, back).',
+    oneOf: Object.values(JOURNEY_STEP_SCHEMAS)
+};
+export { JOURNEY_STEP_SCHEMAS };
+export default journeyStepSchema;

package/dist/journeyGrammar/normaliseJourneySteps.js

@@ -0,0 +1,31 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+// Rewrites the grammar's shorthands into their full form, so the runner reads
+// one shape per step: `wait: 3000` becomes `wait: { ms: 3000 }`. Runs on steps
+// validateJourneySteps accepted.
+function normaliseJourneySteps({ steps }) {
+    return steps.map((step)=>{
+        if (type.isNumber(step.wait)) {
+            return {
+                wait: {
+                    ms: step.wait
+                }
+            };
+        }
+        return step;
+    });
+}
+export default normaliseJourneySteps;

package/dist/journeyGrammar/validateJourneySteps.js

@@ -13,6 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { type } from '@lowdefy/helpers';
+import JOURNEY_STEP_EXAMPLES from './journeyStepExamples.js';
 const STEP_KEYS = [
     'click',
     'open',
@@ -260,7 +261,11 @@ function validateBlockValue({ key, params }) {
         requireBlockId: true
     });
 }
+// wait takes { ms }, { request } or { state }; a bare number is read as { ms }.
 function validateWait(params) {
+    if (type.isNumber(params)) {
+        return undefined;
+    }
     if (!type.isObject(params)) {
         return `Step "wait" requires one of { ms }, { request }, { state }. Received ${describe(params)}.`;
     }
@@ -505,6 +510,22 @@ function validatePlacement({ step, previous }) {
     }
     return undefined;
 }
+// The examples an error about this step ends with: the expect kind's own when
+// the step names a known one.
+function getExamplesKey(step) {
+    const key = getStepKey(step);
+    if (key === 'expect' && type.isObject(step.expect)) {
+        const expectKey = getStepKey(step.expect);
+        if (EXPECT_KEYS.includes(expectKey)) {
+            return `expect.${expectKey}`;
+        }
+    }
+    return key;
+}
+function withExamples({ message, step }) {
+    const examples = JOURNEY_STEP_EXAMPLES[getExamplesKey(step)];
+    return `${message} Example: ${examples.map(describe).join(' or ')}.`;
+}
 // Validates one step's shape. Returns an error message, or undefined when the
 // step is well-formed.
 function validateStep(step) {
@@ -516,7 +537,19 @@ function validateStep(step) {
         const received = type.isUndefined(key) ? Object.keys(step).join(', ') : key;
         return `Unknown journey step "${received}". Steps are: ${STEP_KEYS.join(', ')}.`;
     }
-    const params = step[key];
+    const message = validateStepParams({
+        key,
+        params: step[key]
+    });
+    if (type.isUndefined(message)) {
+        return undefined;
+    }
+    return withExamples({
+        message,
+        step
+    });
+}
+function validateStepParams({ key, params }) {
     switch(key){
         case 'click':
             return validateClick(params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/node-utils",
-  "version": "0.0.0-experimental-20261006165558",
+  "version": "0.0.0-experimental-20261007124348",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -34,9 +34,10 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/errors": "0.0.0-experimental-20261006165558",
-    "@lowdefy/helpers": "0.0.0-experimental-20261006165558",
+    "@lowdefy/errors": "0.0.0-experimental-20261007124348",
+    "@lowdefy/helpers": "0.0.0-experimental-20261007124348",
     "fs-extra": "11.3.4",
+    "undici": "7.30.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {
@@ -44,6 +45,7 @@
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.32",
     "@swc/jest": "0.2.39",
+    "ajv": "8.20.0",
     "copyfiles": "2.4.1",
     "jest": "28.1.3"
   },