primitive-admin 1.1.0-alpha.6 → 1.1.0-alpha.60

package/dist/src/lib/workflow-payload.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared TOML → workflow-payload builder (#1177).
+ *
+ * Background: the CLI built the create/update workflow payload in THREE
+ * separate hand-enumerated literals — `workflows create --from-file`
+ * (`cli/src/commands/workflows.ts`), the `sync push` create branch
+ * (`cli/src/commands/sync.ts`), and the `sync push` update branch (the metadata
+ * PATCH in `cli/src/lib/workflow-apply.ts`). Because each site listed the
+ * `[workflow]` fields by hand, they drifted apart: a field added to one path was
+ * silently dropped by the others. `status` was the 4th field lost this way
+ * (after `syncCallable` #807, `accessRule` #571, `runAs` #1081); the audit also
+ * found `capabilities` (#1172) and `perAppMaxRunning` / `perAppMaxQueued` /
+ * `queueTtlSeconds` dropped from at least one path.
+ *
+ * The fix: one shared builder that owns the `[workflow]`-derived field list.
+ * All three call-sites spread its output; only the per-field presence coalescing
+ * and the create-only `syncCallable` inclusion differ by `mode`, so the field
+ * list itself lives in exactly one place and can't drift again. A unit
+ * drift-guard asserts the builder's key set (see
+ * `cli/tests/unit/workflow-payload-fields.test.ts`).
+ *
+ * What the builder does NOT own (structural / call-site-specific wiring the
+ * callers still attach): `workflowKey`, `steps`, and the `metadataManifest`
+ * declared-access manifest (#1304) — the sync paths always attach it, create
+ * --from-file never does.
+ *
+ * Presence semantics, by mode:
+ *   - create: optional strings coalesce absent/empty → `undefined` (omit; the
+ *     server default applies). `capabilities` forwards the raw array (absent →
+ *     omit). Schemas omit when absent.
+ *   - update: optional strings distinguish explicit-clear from leave-unset via
+ *     `x !== undefined ? (x || null) : undefined`. `status` forwards the bare
+ *     value (matching the server's hasOwnProperty path). Schemas send `null`
+ *     when absent so a cleared schema round-trips.
+ *   - booleans (`requiresClientApply`, and `syncCallable` on create) are raw
+ *     pass-through so an explicit `false` is preserved and only a truly-absent
+ *     key drops.
+ *   - `syncCallable` is OMITTED in `mode: "update"`: the server re-validates
+ *     `syncCallable: true` against the CURRENTLY-active steps, so the update
+ *     path must send it as a deferred second PATCH after the new steps are live
+ *     (#807). `applyWorkflowBody` owns that second PATCH.
+ */
+export type WorkflowPayloadMode = "create" | "update";
+/**
+ * Parse a JSON schema field that TOML may present as a string OR (for an inline
+ * table) as an already-parsed object. Kept here in `cli/src/lib` so the builder
+ * owns its own parse decision rather than importing back into a command module
+ * (#1177 dependency-direction decision).
+ */
+export declare function safeJsonParse(value: any): any;
+/**
+ * #1614 — the workflow-level named `expr.*` definitions payload. Phase 1
+ * carries CEL guard definitions only (`cel`); `[expr.template]` is a deferred
+ * later phase.
+ */
+export type WorkflowExpressionsPayload = {
+    cel?: Record<string, string>;
+};
+/**
+ * #1614 — extract the top-level `[expr.cel]` table from a parsed workflow TOML
+ * into the `expressions` payload the server persists on the R2 steps blob. A
+ * structural field (like `steps` / `metadataManifest`), attached alongside the
+ * steps write — NOT a `[workflow]`-table field. Returns `undefined` when no
+ * `[expr.cel]` table (or no string entries) is present, so a workflow without
+ * definitions round-trips a clean drop.
+ *
+ * `tomlData.expr.cel` is the parsed `[expr.cel]` table: `{ <name>: <cel-string> }`.
+ */
+export declare function parseWorkflowExpressionsToml(tomlData: any): WorkflowExpressionsPayload | undefined;
+/**
+ * The `[workflow]`-derived keys the builder emits, per mode — read from the
+ * vendored definition (#2644), not restated here. A field added to
+ * `src/config-surface/workflow.ts` is pushed with no edit to this file, which
+ * is what closes the recurring "CLI silently drops a new server field" bug.
+ */
+export declare function workflowPayloadFields(mode: WorkflowPayloadMode): string[];
+/**
+ * Build the workflow payload's `[workflow]`-derived fields from a parsed TOML
+ * `[workflow]` table. `workflow` is `tomlData.workflow` (already merged with any
+ * explicit CLI flag overrides by the caller). Callers spread the result into
+ * the create/update payload and attach the structural fields themselves
+ * (`workflowKey`, `steps`, `metadataManifest`).
+ */
+export declare function buildWorkflowPayloadFromToml(workflow: any, { mode }: {
+    mode: WorkflowPayloadMode;
+}): Record<string, any>;

package/dist/src/lib/workflow-payload.js

@@ -0,0 +1,168 @@
+/**
+ * Shared TOML → workflow-payload builder (#1177).
+ *
+ * Background: the CLI built the create/update workflow payload in THREE
+ * separate hand-enumerated literals — `workflows create --from-file`
+ * (`cli/src/commands/workflows.ts`), the `sync push` create branch
+ * (`cli/src/commands/sync.ts`), and the `sync push` update branch (the metadata
+ * PATCH in `cli/src/lib/workflow-apply.ts`). Because each site listed the
+ * `[workflow]` fields by hand, they drifted apart: a field added to one path was
+ * silently dropped by the others. `status` was the 4th field lost this way
+ * (after `syncCallable` #807, `accessRule` #571, `runAs` #1081); the audit also
+ * found `capabilities` (#1172) and `perAppMaxRunning` / `perAppMaxQueued` /
+ * `queueTtlSeconds` dropped from at least one path.
+ *
+ * The fix: one shared builder that owns the `[workflow]`-derived field list.
+ * All three call-sites spread its output; only the per-field presence coalescing
+ * and the create-only `syncCallable` inclusion differ by `mode`, so the field
+ * list itself lives in exactly one place and can't drift again. A unit
+ * drift-guard asserts the builder's key set (see
+ * `cli/tests/unit/workflow-payload-fields.test.ts`).
+ *
+ * What the builder does NOT own (structural / call-site-specific wiring the
+ * callers still attach): `workflowKey`, `steps`, and the `metadataManifest`
+ * declared-access manifest (#1304) — the sync paths always attach it, create
+ * --from-file never does.
+ *
+ * Presence semantics, by mode:
+ *   - create: optional strings coalesce absent/empty → `undefined` (omit; the
+ *     server default applies). `capabilities` forwards the raw array (absent →
+ *     omit). Schemas omit when absent.
+ *   - update: optional strings distinguish explicit-clear from leave-unset via
+ *     `x !== undefined ? (x || null) : undefined`. `status` forwards the bare
+ *     value (matching the server's hasOwnProperty path). Schemas send `null`
+ *     when absent so a cleared schema round-trips.
+ *   - booleans (`requiresClientApply`, and `syncCallable` on create) are raw
+ *     pass-through so an explicit `false` is preserved and only a truly-absent
+ *     key drops.
+ *   - `syncCallable` is OMITTED in `mode: "update"`: the server re-validates
+ *     `syncCallable: true` against the CURRENTLY-active steps, so the update
+ *     path must send it as a deferred second PATCH after the new steps are live
+ *     (#807). `applyWorkflowBody` owns that second PATCH.
+ */
+import { writableFieldNames } from "./generated-config-surfaces.js";
+import { WORKFLOW_TABLE } from "./config-surface.js";
+/**
+ * Parse a JSON schema field that TOML may present as a string OR (for an inline
+ * table) as an already-parsed object. Kept here in `cli/src/lib` so the builder
+ * owns its own parse decision rather than importing back into a command module
+ * (#1177 dependency-direction decision).
+ */
+export function safeJsonParse(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return JSON.parse(value);
+    return value; // Already an object (TOML parsed it as a table)
+}
+/**
+ * #1614 — extract the top-level `[expr.cel]` table from a parsed workflow TOML
+ * into the `expressions` payload the server persists on the R2 steps blob. A
+ * structural field (like `steps` / `metadataManifest`), attached alongside the
+ * steps write — NOT a `[workflow]`-table field. Returns `undefined` when no
+ * `[expr.cel]` table (or no string entries) is present, so a workflow without
+ * definitions round-trips a clean drop.
+ *
+ * `tomlData.expr.cel` is the parsed `[expr.cel]` table: `{ <name>: <cel-string> }`.
+ */
+export function parseWorkflowExpressionsToml(tomlData) {
+    const cel = tomlData?.expr?.cel;
+    if (!cel || typeof cel !== "object" || Array.isArray(cel))
+        return undefined;
+    const out = {};
+    for (const [name, body] of Object.entries(cel)) {
+        if (typeof body === "string")
+            out[name] = body;
+    }
+    return Object.keys(out).length > 0 ? { cel: out } : undefined;
+}
+/**
+ * Fields the SERVER accepts on update but the CLI deliberately sends only on
+ * create. This is a sequencing invariant, not a statement about the server:
+ * `syncCallable: true` is re-validated against the CURRENTLY-active steps, so
+ * the update path defers it to a second PATCH once the new steps are live
+ * (#807 — `applyWorkflowBody` owns that). The definition correctly declares
+ * `writableOn: ["create", "update"]`; the exception lives here, where the
+ * ordering decision is.
+ */
+const CREATE_ONLY_ON_THE_WIRE = new Set(["syncCallable"]);
+/**
+ * The `[workflow]`-derived keys the builder emits, per mode — read from the
+ * vendored definition (#2644), not restated here. A field added to
+ * `src/config-surface/workflow.ts` is pushed with no edit to this file, which
+ * is what closes the recurring "CLI silently drops a new server field" bug.
+ */
+export function workflowPayloadFields(mode) {
+    const fields = writableFieldNames(WORKFLOW_TABLE, mode);
+    return mode === "create"
+        ? fields
+        : fields.filter((f) => !CREATE_ONLY_ON_THE_WIRE.has(f));
+}
+/**
+ * Per-field value producers, keyed by the definition's field name. A field with
+ * no entry is a scalar passthrough: the TOML value is forwarded as-is (absent →
+ * `undefined`, which `JSON.stringify` drops so the server default applies).
+ * That is what makes a passthrough field authorable by editing the definition
+ * alone (#2644 criterion 1); the entries below are the fields whose presence
+ * semantics are genuinely their own.
+ */
+const PAYLOAD_VALUE = {
+    // status — create coalesces absent/empty → omit (server default `draft`
+    // applies); update forwards the bare value so it round-trips and an
+    // explicit "" surfaces the server's validation error rather than a silent
+    // no-op (matches the pre-existing update path).
+    status: (value, create) => (create ? value || undefined : value),
+    // accessRule / runAs — create coalesces absent/empty → omit; update
+    // distinguishes explicit clear ("" → null) from leave-unset (absent →
+    // undefined).
+    accessRule: (value, create) => create
+        ? value || undefined
+        : value !== undefined
+            ? value || null
+            : undefined,
+    runAs: (value, create) => create
+        ? value || undefined
+        : value !== undefined
+            ? value || null
+            : undefined,
+    // Schemas — parse a JSON string (or accept an inline table). Create omits
+    // when absent; update sends null so a cleared schema round-trips.
+    inputSchema: (value, create) => value ? safeJsonParse(value) : create ? undefined : null,
+    outputSchema: (value, create) => value ? safeJsonParse(value) : create ? undefined : null,
+    // #1972 — declarative run-scoped lock (`[workflow.lock]`, #1518 Phase 3).
+    // A TOML-owned nested-object field, mirroring the schemas above. Presence-
+    // keyed, not truthiness-keyed: forward the value whenever the KEY is present
+    // (`!== undefined`) — the server's create/PATCH accept an object OR a JSON
+    // string, so a present-but-malformed falsy value (`lock = false`/`0`) must
+    // be forwarded so the server surfaces its validation error, rather than
+    // being silently treated as absent (dropped on create, cleared on update).
+    // Absent on create → omit (server default: no lock); absent on update →
+    // null so removing `[workflow.lock]` clears the server-side lock
+    // (config-as-code). Before this the field was dropped from both sync paths,
+    // so a pull → push cycle silently lost the lock (#1972).
+    lock: (value, create) => value !== undefined ? value : create ? undefined : null,
+};
+/**
+ * Build the workflow payload's `[workflow]`-derived fields from a parsed TOML
+ * `[workflow]` table. `workflow` is `tomlData.workflow` (already merged with any
+ * explicit CLI flag overrides by the caller). Callers spread the result into
+ * the create/update payload and attach the structural fields themselves
+ * (`workflowKey`, `steps`, `metadataManifest`).
+ */
+export function buildWorkflowPayloadFromToml(workflow, { mode }) {
+    const create = mode === "create";
+    const payload = {};
+    for (const field of workflowPayloadFields(mode)) {
+        const descriptor = WORKFLOW_TABLE.fields.find((f) => f.field === field);
+        const tomlKey = descriptor?.tomlKey ?? field;
+        const produce = PAYLOAD_VALUE[field];
+        payload[field] = produce
+            ? produce(workflow[tomlKey], create, workflow)
+            : // Scalar passthrough: queue limits, dequeueOrder, name, description,
+                // capabilities, and the boolean flags — raw so an explicit `false`
+                // survives and only a truly-absent key drops.
+                workflow[tomlKey];
+    }
+    return payload;
+}
+//# sourceMappingURL=workflow-payload.js.map

package/dist/src/lib/workflow-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-payload.js","sourceRoot":"","sources":["../../../src/lib/workflow-payload.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/workflow-toml-validator.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Push-time validator for workflow TOML files (issue #685, #998).
+ *
+ * Detects the common footgun where a user writes `[steps.<id>.<field>]` under
+ * an open `[[steps]]` array. TOML parses that as a sub-table on the
+ * most-recent step keyed by the step's id (e.g. `steps[0]["refresh-each"]`),
+ * not as the intended `steps[0].request`. The result is a step with an
+ * unrecognized top-level field — the runtime silently ignores it, and the
+ * step then runs with an empty `request` block.
+ *
+ * The validator walks every step in `tomlData.steps[]`. For a step whose
+ * `kind` the CLI KNOWS about, it reports any top-level field not in the
+ * generated allowlist. For an UNKNOWN kind (an old CLI run against a newer
+ * server that registered a step kind the CLI doesn't have), it SKIPS the
+ * per-field allowlist check — but still runs the kind-agnostic
+ * misnested-header footgun detector. This is the #998 fix: the recurring
+ * "newer server kind → false-reject of valid fields" failure (#685/#802/#971
+ * were all false rejections) becomes "unvalidated, not rejected."
+ *
+ * ── Source of truth (#998) ───────────────────────────────────────────────
+ * The allowlist field union and the known-kind set are GENERATED from the
+ * server step runners (`src/workflows/steps/*.ts`) and the universal
+ * `BaseStepDefinition` shape into the committed
+ * `cli/src/lib/generated-allowlist.ts` artifact (the CLI does NOT import
+ * server `src/` at runtime — only the build-time generator does). The union is
+ * derived from what each runner READS, not what the `*StepDefinition` TYPE
+ * declares — types over-declare and would weaken the footgun detector. A CI
+ * freshness guard (`gen-allowlist.mjs --check`, also asserted by the #985
+ * drift-guard test) keeps the committed artifact in sync with the runners, so
+ * the hand-edit drift class (#685/#802/#971) cannot recur for the same-version
+ * case. Regenerate with `node cli/scripts/gen-allowlist.mjs`.
+ */
+/**
+ * Read-only view of `ALLOWLISTED_FIELDS` for the drift-guard test (#985).
+ *
+ * Exported so `cli/tests/unit/workflow-toml-validator-drift-guard.test.ts` can
+ * assert this set stays a superset of every top-level field the step runners
+ * in `src/workflows/steps/*.ts` actually read — checking the *live* set the
+ * validator enforces rather than a copy that could itself drift. Not part of
+ * the public validator API; consumed only by the guard.
+ */
+export declare const ALLOWLISTED_FIELDS_FOR_DRIFT_GUARD: ReadonlySet<string>;
+/**
+ * Read-only view of `KNOWN_KINDS` for the drift-guard test (#998). Lets the
+ * guard assert the generated known-kind set matches a fresh scan.
+ */
+export declare const KNOWN_KINDS_FOR_DRIFT_GUARD: ReadonlySet<string>;
+/**
+ * A single offending field on a step.
+ *
+ * `stepIndex` is the array index in `steps[]`.
+ * `stepId` is the value of the step's `id` field, if any (string).
+ * `field` is the unknown top-level key; uses sentinel names for shape
+ * errors:
+ *  - `__steps_shape__`: `steps` is not an array (table or scalar).
+ *  - `__step_shape__`: a step is not an object.
+ *  - `__workflow_system_access_rule__`: `[workflow] runAs = "system"` with a
+ *    non-empty `accessRule` — dead config the server rejects (#1447/#1258).
+ *    A workflow-level error (not tied to a step): `stepIndex: -1, stepId: null`.
+ *  - `__template_expression__`: a `{{ }}` expression that can never resolve
+ *    (#2689). The field itself is valid — the `hint` carries the expression's
+ *    location and the lint's message.
+ * `hint` is a short, user-facing explanation (used by
+ * `formatWorkflowTomlErrors` to render the multi-line diagnostic).
+ * `parentStepId` is set when this error came from a `collect` step's
+ * nested inner `step` definition (codex review, 2026-05-15): the outer
+ * `stepIndex` points at the array index, `parentStepId` carries the
+ * outer step's id (if any), and `stepId` carries the inner step's id.
+ * It's `null` for top-level errors (the renderer treats both `null` and
+ * `undefined` as top-level — see `formatWorkflowTomlErrors`).
+ */
+export type WorkflowTomlError = {
+    stepIndex: number;
+    stepId: string | null;
+    field: string;
+    hint: string;
+    parentStepId?: string | null;
+};
+/**
+ * #1447 workflow-identity predicate, extracted (codex review, 2026-07-15) so
+ * command sites that apply command-line metadata overrides can re-run it
+ * against the merged/effective workflow rather than only the parsed file.
+ *
+ * `runAs = "system"` + a non-empty `accessRule` is dead config: a system run
+ * can only be started by the system and never evaluates its accessRule, so any
+ * non-empty rule is inert. The server rejects this at save time (#1258,
+ * `src/workflows/definition-store.ts:271-280`); catching it locally keeps
+ * `sync push` all-or-nothing instead of failing mid-push and leaving partial
+ * server state (#1418 drift).
+ *
+ * Mirrors the server predicate byte-for-byte: returns the sentinel error only
+ * when `runAs === "system"` AND `typeof accessRule === "string"` AND
+ * `accessRule.trim() !== ""`. Default/unset/empty/whitespace-only runAs or
+ * accessRule (and a bare non-string boolean accessRule) return `null`.
+ *
+ * @param workflow The workflow-metadata object — the `[workflow]` table, or
+ *   for commands that accept unwrapped root-level metadata, the root TOML
+ *   object (`tomlData.workflow || tomlData`). Non-object inputs return `null`.
+ */
+export declare function validateWorkflowIdentity(workflow: any): WorkflowTomlError | null;
+/**
+ * #2643 — `templateMissingMarker` was removed from the platform. A workflow
+ * TOML that still sets it is rejected here, before the push, with the same
+ * sentence the server returns, rather than being silently dropped.
+ */
+export declare const REMOVED_TEMPLATE_MISSING_MARKER_MESSAGE: string;
+/**
+ * Non-blocking notes for a workflow TOML — things worth saying on a push that
+ * are not errors.
+ *
+ * #2643: `strict` / `strictParams` are accepted and ignored, because the
+ * failure they used to opt into now applies to every workflow. A definition
+ * that sets them keeps working unchanged, so this is a note, not an error.
+ */
+export declare function collectWorkflowTomlNotes(tomlData: any): string[];
+/** The runAs / accessRule pair the identity lint reads. */
+export interface WorkflowIdentityFields {
+    runAs?: unknown;
+    accessRule?: unknown;
+}
+/**
+ * #1447 (maintainer decision, 2026-07-21): compute the EFFECTIVE workflow
+ * identity that an `update --from-file` push will leave on the server — the
+ * merge of the persisted record with the incoming file/flags.
+ *
+ * `applyWorkflowBody` omits undefined fields, so the server retains whichever
+ * side of the runAs/accessRule pair the incoming payload doesn't set. Linting
+ * the incoming payload alone therefore misses the case where the OTHER side is
+ * already `system` / a stored rule: an existing `runAs="system"` workflow plus
+ * a file adding only an `accessRule`, or a file flipping a workflow with a
+ * stored rule to `runAs="system"`. Both pass a payload-only lint and are then
+ * rejected by the server's PATCH. Merging the two before `validateWorkflowIdentity`
+ * catches them locally at zero extra cost — the persisted record is already
+ * fetched at the call site.
+ *
+ * Presence semantics mirror the update payload builder: a field PRESENT in
+ * `incoming` (including an empty-string clear) overrides the stored value; an
+ * ABSENT field (undefined) falls back to what the server keeps.
+ */
+export declare function effectiveWorkflowIdentity(existing: WorkflowIdentityFields | null | undefined, incoming: WorkflowIdentityFields | null | undefined): WorkflowIdentityFields;
+/**
+ * Walk a parsed workflow TOML document and return all unknown-field errors.
+ *
+ * @param tomlData The output of `parseConfigToml()` for a workflow TOML file.
+ * @param opts.skipWorkflowIdentity When true, suppress the #1447 workflow
+ *   identity check (`runAs="system"` + non-empty `accessRule`). Callers that
+ *   merge command-line overrides after parsing re-run `validateWorkflowIdentity`
+ *   against the effective metadata themselves.
+ * @returns An array of error objects, one per offending field. Empty if no
+ *   errors were found.
+ */
+export declare function validateWorkflowToml(tomlData: any, opts?: {
+    skipWorkflowIdentity?: boolean;
+}): WorkflowTomlError[];
+/**
+ * Render a multi-line diagnostic for a list of errors. Designed for the
+ * shape called out in the issue:
+ *
+ *   Error in workflows/refresh.toml:
+ *     steps[0] (id="refresh-each") has unknown field "refresh-each".
+ *     This is usually caused by writing [steps.refresh-each.request] instead of [steps.request].
+ *     TOML can't address an array element by id — use [steps.request] (refers to the most recent step).
+ *
+ * @param filePath The TOML file path (or display name) to include in the
+ *   header.
+ * @param errors The error list from `validateWorkflowToml`.
+ * @returns A multi-line string ready to print to stderr.
+ */
+export declare function formatWorkflowTomlErrors(filePath: string, errors: WorkflowTomlError[]): string;
+/**
+ * #1614 — client-side mirror of the server's `validateWorkflowExpressions`
+ * (`src/workflows/definition-store.ts`) for named `expr.*` CEL guards. Returns
+ * structural errors so `sync push` fails fast with the same class of diagnostic
+ * the server would 400 on:
+ *   1. every `expr.<name>` reference — in a definition body OR a step guard
+ *      (`runIf` / `successWhen` / switch `when`) — names a DECLARED definition;
+ *   2. the definition reference graph is a DAG (no cycles);
+ *   3. each definition body is a non-empty string.
+ *
+ * The CLI has no CEL parser, so full CEL parse validation stays server-side
+ * (the authoritative check) — this mirror catches the common undeclared-name
+ * and cycle mistakes before a network round-trip, matching how the CLI does
+ * structural checks and the server does authoritative validation elsewhere.
+ */
+/**
+ * #1614 — validate the RAW `[expr.cel]` table shape BEFORE
+ * `parseWorkflowExpressionsToml` filters it. That parser drops any entry whose
+ * body is not a string, so a mistyped `ready = true` would vanish and, with no
+ * references left to fail on, `sync push` would succeed while omitting the whole
+ * expression table. Surface non-string / empty / wrong-typed bodies (and a
+ * non-table `cel`) as a hard CLI validation error instead. Mirrors the server's
+ * `validateRawExpressionsShape` (`src/workflows/definition-store.ts`).
+ *
+ * `tomlData.expr.cel` is the parsed `[expr.cel]` table.
+ */
+export declare function validateWorkflowExpressionsRawToml(tomlData: any): string[];
+export declare function validateWorkflowExpressionsToml(steps: any[], expressions: {
+    cel?: Record<string, string>;
+} | undefined): string[];