@octaviaflow/flow-rules 0.6.0 → 0.8.0

package/dist/rules/configContracts.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ONE answer to "what does this step's config look like?"
+ *
+ * THE PROBLEM THIS EXISTS TO END. Every action carried its shape in two places
+ * that never spoke to each other:
+ *
+ *   index.ts   `inputSchema.fields` — what `describe_action_type` reports to an
+ *              agent and what the config fence enforces;
+ *   config.ts  `XxxConfig.schema` + `validate()` — what the panel actually binds
+ *              and what the platform's own validation checks.
+ *
+ * `index.ts` never imported `config.ts`, so they drifted. Measured:
+ *   - `transform` declared 2 input fields; its panel binds 13.
+ *   - `variables` declared 0; the real key is `fields` — an agent guessed
+ *     `variables`, was told "no fields defined", and gave up on the action.
+ *   - `slack_message` declared `message`; the panel stores `text`; the engine
+ *     accepts either — so an agent wrote `message`, Slack received it, and the
+ *     panel showed an empty box. Its own `config.ts` had said all along:
+ *     "Canonical message body: `text`. Legacy alias: `message`."
+ *   - On beta, 71 of 131 real config keys were undeclared.
+ *
+ * The agent was fed the stale half of the catalog and did exactly what it was
+ * told. So this module makes `config.ts` the source of truth: every consumer
+ * that needs a step's shape — the fence, `describe_action_type`, the editor —
+ * reads `contractFieldsFor(definition)`, which is `inputSchema` (kept for its
+ * labels, descriptions and option lists) UNIONED with everything the contract
+ * declares. A key the contract knows can no longer be "undeclared".
+ *
+ * And `contractDrift()` is a TEST: any `inputSchema` key the contract does not
+ * recognise fails the build. That is what would have caught `message`.
+ */
+import type { ActionDefinition, FieldConfig } from "../catalog/types";
+/** The vocabulary the `config.ts` schema maps already use. Not extended. */
+export type ContractFieldType = "string" | "text" | "select" | "json" | "connection" | "number" | "boolean" | "array" | "object" | "url" | "expression" | "code" | "none";
+/**
+ * A field as the `config.ts` maps actually write it. `type` is the vocabulary
+ * above, but the maps are plain object literals (so TypeScript sees `string`),
+ * and several carry `description`/`min` for the panel. The vocabulary is
+ * enforced at derivation — an unknown type becomes a String field and is
+ * flagged by `contractVocabularyDrift` — rather than by making 22 files cast.
+ */
+export interface ContractField {
+    type: string;
+    required?: boolean;
+    options?: ReadonlyArray<string | number>;
+    [extra: string]: unknown;
+}
+export interface ConfigContract {
+    schema: Readonly<Record<string, ContractField>>;
+    /** The platform's own check, exactly as the panel runs it. */
+    validate?: (config: Record<string, unknown>) => {
+        valid: boolean;
+        errors: string[];
+    };
+}
+/**
+ * Every action that has a `config.ts`. Keyed by action id.
+ *
+ * Fourteen actions have no contract yet (group, ai_agent, idp_extract, the
+ * file-format and storage actions, connector_trigger). For those,
+ * `contractFor` returns undefined and consumers fall back to `inputSchema`
+ * alone — which is exactly what they did before, so nothing regresses. Adding a
+ * contract for one of them is a `config.ts` plus one line here.
+ */
+export declare const CONFIG_CONTRACTS: Readonly<Record<string, ConfigContract>>;
+export declare function contractFor(actionId: string | undefined): ConfigContract | undefined;
+/** Keys the contract declares — `none`-typed placeholders excluded. */
+export declare function declaredKeys(actionId: string | undefined): string[];
+/**
+ * Keys the EDITOR persists for itself — `_outputSchema`, `_lastOutput`,
+ * `_outputSchemaHash`, `sampledColumnSchemas`-style caches. They are derived,
+ * never authored, and a value in one of them is a snapshot the editor will
+ * overwrite. Nothing outside the editor should write them, and an agent that
+ * does is writing a lie the next open will erase.
+ */
+export declare function isEditorPrivateKey(key: string): boolean;
+/**
+ * What a step ACCEPTS: `inputSchema.fields` — kept, because it carries labels,
+ * descriptions and option lists worth showing — unioned with every contract
+ * key it forgot. The single thing the fence, `describe_action_type` and the
+ * editor should read.
+ */
+export declare function contractFieldsFor(definition: ActionDefinition): FieldConfig[];
+/**
+ * `inputSchema` keys the contract does NOT know. A non-empty result is a bug:
+ * `describe_action_type` is advertising a key the platform does not store under
+ * that name. `slack_message.message` was one. The test over the whole catalog
+ * fails on any of these, so it cannot happen quietly again.
+ */
+export declare function contractDrift(definition: ActionDefinition): string[];
+/** Contract fields whose `type` is not in the vocabulary — a typo, not a new kind. */
+export declare function contractVocabularyDrift(actionId: string): string[];

package/dist/rules/mappingFunctions.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The functions a Field Mapper `transform` may call — implementations AND the
+ * list, in one place.
+ *
+ * WHY THIS EXISTS. A Transform step's mapping has two slots, and they are not
+ * interchangeable:
+ *
+ *   sourceField  names a FIELD          `{{Website}}`
+ *   transform    transforms the VALUE   `uppercase(value)`
+ *
+ * Neither one evaluates an expression. `sourceField` is a literal path lookup,
+ * and `transform` is a single function call — so anything clever written in
+ * either resolves to nothing. Both failure modes were silent: a bad
+ * `sourceField` wrote an EMPTY value on every record, and an unknown
+ * `transform` function returned the source value unchanged, with a comment in
+ * the engine that said so out loud ("an unknown built-in falls through
+ * silently"). An agent hit the first one and blanked a field on every customer
+ * a live flow synced.
+ *
+ * Shipping the list without the implementations would just move the drift: the
+ * UI's FX sidebar already advertises 99 functions while the engine's mapping
+ * executor accepted 10, and four of those ten were not in the sidebar at all.
+ * So this module owns BOTH. One import, nothing to keep in step.
+ *
+ * ADDING ONE: put it in `MAPPING_FUNCTIONS` with a `MAPPING_FUNCTION_SPECS`
+ * entry. The spec is what the editor lists and what an agent is shown, so a
+ * function without one is invisible and effectively does not exist.
+ */
+/** A value-transform. `value` is the resolved source; the rest are literals. */
+export type MappingFunction = (...args: unknown[]) => unknown;
+export interface MappingFunctionSpec {
+    name: string;
+    /** How it is written, for the picker and for an agent's tool description. */
+    signature: string;
+    description: string;
+    example: string;
+}
+export declare const MAPPING_FUNCTIONS: Record<string, MappingFunction>;
+export declare const MAPPING_FUNCTION_SPECS: readonly MappingFunctionSpec[];
+/** Custom functions are written by the workspace and resolved at run time. */
+export declare const USER_FUNCTION_PREFIX = "user.";
+/**
+ * Is this a function a mapping may call?
+ *
+ * `user.*` is accepted on name alone — the workspace's own functions are
+ * resolved from a registry at run time, and this module cannot know them.
+ */
+export declare function isMappingFunction(name: string): boolean;
+/**
+ * The function a `transform` calls, or `null` when it is not a call at all.
+ *
+ * Mirrors the engine's parsing exactly, including the back-compat shim: a BARE
+ * name (`uppercase`) means `uppercase(value)`, because older saved mappings
+ * persisted just the name.
+ */
+export declare function mappingTransformFunctionName(transform: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The flow action catalog and the rules engine behind Flow Doctor \u2014 one definition of what a step accepts and what makes a flow valid, shared by the editor and the server",
   "type": "module",
   "main": "./dist/index.cjs",