# @octaviaflow/flow-rules

> The flow action catalog and the rules engine behind Flow Doctor — one definition of what a step accepts and what makes a flow valid, shared by the editor and the server

Latest version **0.6.0** (published 2026-09-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @octaviaflow/flow-rules
pnpm add @octaviaflow/flow-rules
yarn add @octaviaflow/flow-rules
bun add @octaviaflow/flow-rules
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.6.0 |
| Published | 2026-09-24 |
| First published | 2026-09-24 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 394.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Octaviaflow Team |
| Maintainers | vishal035 |
| Keywords | octaviaflow, workflow, actions, validation, flow-doctor |

## Links

- npm: https://www.npmjs.com/package/@octaviaflow/flow-rules
- Repository: https://github.com/OctaviaFlow/Octaviaflow-System
- Homepage: https://github.com/OctaviaFlow/Octaviaflow-System/tree/main/Octaviaflow-Flow-Rules#readme
- Issues: https://github.com/OctaviaFlow/Octaviaflow-System/issues
- npm.io page: https://npm.io/package/@octaviaflow/flow-rules

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 0.6.0 (latest) — 2026-09-24
- 0.5.0 — 2026-09-24
- 0.4.0 — 2026-09-24
- 0.3.1 — 2026-09-24
- 0.3.0 — 2026-09-24
- 0.2.0 — 2026-09-24
- 0.1.1 — 2026-09-24
- 0.1.0 — 2026-09-24

## README

# @octaviaflow/flow-rules

The flow **action catalog** and the **rules engine behind Flow Doctor** — the
two things that decide what a step accepts and whether a flow works.

## Why this exists

Both lived in `octaviaflow-ui`, so both were reachable only from a browser.
That was fine while the editor was the only thing building flows. It stopped
being fine when an AI agent became a second author (DEV-391):

- an agent that cannot read an action's `inputSchema` **guesses** at the
  config, and a guessed config is a flow that fails at run time on the
  customer's live systems;
- an agent that cannot run the rules cannot tell whether what it built works,
  so it reports success and hands over a broken flow.

Copying either into Backend would have produced two rule sets that agree on
the day they are written — the same failure mode as a duplicated permission
predicate, and the copy that drifts would be the one the agent trusts.

So they live here, and both the editor and the server import them. The editor
keeps validating in-process on every structural canvas change; Backend gets
the identical verdict for `check_flow`.

## What is and is not here

**Here:** the `ActionDefinition` catalog (ids, descriptions, `inputSchema`,
`outputSchema`), the workflow validator, node config status, and the id
generators, so a caller building a flow makes ids the editor recognises.

**Not here:** React. The config **panels** stay in `octaviaflow-ui` — a
component in this package would make it unusable from Backend, which is the
whole point. `ActionDefinition.icon` is a string key the consumer's catalog
adapter resolves; this package never names a component.

## Usage

```ts
import {
  getAllActions,
  getActionById,
  validateWorkflow,
  getNodeConfigStatus,
} from "@octaviaflow/flow-rules";

// What may this step be configured with?
const action = getActionById("http_request");
const required = action?.inputSchema.fields.filter((f) => f.validation?.required);

// Does this flow work?
const { isValid, errors, warnings } = validateWorkflow(nodes, edges);
```

### The severity contract

Unchanged from rules-v2 (DEV-220, ADR-flow-pause-and-rules-v2):

| | |
|---|---|
| `error` | the flow cannot work as built. **Blocks activation.** |
| `warning` | it will run, but probably not the way the author thinks. Blocks nothing. |

**Saving is never blocked.** A caller that treats a warning as a failure will
refuse flows the editor accepts.

### One field name worth knowing

A node names its action with **`actionDefinitionId`**, not `actionId`. The
latter looks right and silently matches nothing — which is exactly the kind of
mistake this package exists to stop an agent making.

## Commands

```bash
bun install
bun test
bun run typecheck
bun run build      # tsc → dist (ESM + .d.ts), which is what consumers get
```

It ships **built** ESM plus declarations rather than raw TypeScript
(`@octaviaflow/connector-crypto` ships source, but that package is only
consumed by Bun services — `octaviaflow-ui` is Next.js and would need
`transpilePackages` for source).

## Consumers

| Repo | Uses |
|---|---|
| `octaviaflow-ui` | the editor: catalog, live validation, node status badges |
| `Octaviaflow-Backend` | `check_flow` and the agent authoring routes it serves |
| `Octaviaflow-MCP` | indirectly, through Backend |

A change to a rule or an action schema changes what the agent may build. Run
both consumers' suites before publishing.

---
_Source: https://npm.io/package/@octaviaflow/flow-rules · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._