open-index/open-npm huggingface dataset:
npm package: @jeffansay35/fca-ui-guardrail
Description: FCA ↔ UI guardrail enforcing intent-based frontend architecture
Latest version: 1.2.0

# @dipz/fca-ui-guardrail

Tiny **dev-only guardrail** to keep UI aligned with intent.

If you like calm frontend code, this helps.  
If not, you probably won’t use it.

---

## Install

```bash
npm install @dipz/fca-ui-guardrail
```

---

## Copy–Paste Usage (the whole pattern)

```tsx
import {
  explain,
  assertActionAllowed,
  guardIntent,
} from "@dipz/fca-ui-guardrail";

export function CheckoutButton({ intent, dispatch }) {
  // 1. Guard the intent (dev only)
  const safeIntent = guardIntent(intent);

  // 2. Declare what this component uses
  explain(safeIntent, {
    component: "CheckoutButton",
    uses: [
      "ui.visibility.checkoutButton",
      "ui.enabled.checkoutButton",
      "actions.primary",
    ],
  });

  // 3. Render purely from intent
  if (!safeIntent.ui.visibility.checkoutButton) return null;

  return (
    <button
      disabled={!safeIntent.ui.enabled.checkoutButton}
      onClick={() => {
        assertActionAllowed(safeIntent, "primary");
        dispatch(safeIntent.actions.primary);
      }}
    >
      Checkout
    </button>
  );
}
```

That’s it.  
No other setup required.

---

## What This Does

- Throws if UI reads a field that doesn’t exist
- Throws if UI dispatches a forbidden action
- Prevents UI from inventing logic
- Makes refactors safer
- Keeps AI edits from drifting

Errors are loud and immediate.

---

## What This Does NOT Do

- Does not decide business logic
- Does not manage state
- Does not run in production
- Does not replace your framework

Dev-time guard only.

---

## Optional: Project Awareness (CLI)

This package also includes an **optional CLI** that scans your project and
builds a lightweight **UI usage map**.

### Run the scanner

```bash
npx fca-ui-guardrail
```

This will generate:

```
docs/
  ai/
    bridge.json
    summary.md
```

---

### Accept intentional changes

```bash
npx fca-ui-guardrail --update
```

---

## Mental Rule

> UI reads intent.  
> UI does not think.

---

## License

MIT