@octaviaflow/flow-rules 0.7.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.7.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",