npm package: @mnde/orbit-validator
Description: Orbit Protocol v1.0 reference validator (JavaScript)
Latest version: 1.0.0

# Orbit Protocol – JavaScript Validator & CLI

Orbit is a **minimal, fail-closed protocol** for encoding single-action intents as JSON.
This package provides the **reference JavaScript (Node.js) validator** for **Orbit Protocol v1.0**,
plus a small CLI for validation in terminals and CI.

This library is deliberately boring:
- Deterministic
- Schema-locked
- No side effects
- No execution of intents
- Validation only

If an intent is invalid, it is rejected. There is no “best guess.”

---

## What this package is

- A **reference validator** for Orbit Protocol v1.0
- A **Node.js SDK** for programmatic validation
- A **CLI tool** for validating JSON files
- A baseline for **cross-language parity** (Java, Kotlin, etc.)

## What this package is NOT

- An intent executor
- A workflow engine
- A permission system
- A UI framework
- A smart interpreter

Orbit separates **intent validation** from **intent execution** by design.

---

## Install

### Global (CLI)

```bash
npm install -g @mnde/orbit-validator
```

### Local (library)

```bash
npm install @mnde/orbit-validator
```

---

## CLI Usage

Validate an intent file:

```bash
orbit validate intent.json
```

### Exit codes

| Code | Meaning |
|----|--------|
| 0 | Valid Orbit v1.0 intent |
| 1 | Invalid intent |
| 2 | Usage, file, or JSON error |

### Example

```bash
orbit validate valid.json
# VALID
```

```bash
orbit validate invalid.json
# INVALID: ERR_OPEN_URL_REQUIRED
```

---

## Programmatic Usage

```ts
import { validateOrbitIntent } from "@mnde/orbit-validator";

const intent = {
  orbit: "1.0",
  id: "example-123",
  action: "open",
  payload: {
    url: "https://example.com"
  }
};

const result = validateOrbitIntent(intent);

if (result.valid) {
  console.log("Intent is valid");
} else {
  console.error("Invalid intent:", result.code);
}
```

---

## Orbit v1.0 Validation Rules

### Required fields

- `orbit` — must be exactly `"1.0"`
- `id` — non-empty string
- `action` — string from the allowed vocabulary
- `payload` — object

### Allowed actions (v1.0)

| Action | Requirements |
|------|-------------|
| `open` | `payload.url` must be a non-empty string |

Unknown actions are rejected.

---

## Error Codes

Error codes are **stable** and **intentional**.
They are designed to match across all Orbit SDKs.

| Code | Meaning |
|----|--------|
| `ERR_NOT_OBJECT` | Root value is not an object |
| `ERR_ORBIT_VERSION` | Missing or invalid Orbit version |
| `ERR_ID_INVALID` | Missing or invalid `id` |
| `ERR_ACTION_INVALID` | Missing or invalid `action` |
| `ERR_ACTION_UNKNOWN` | Action not in v1.0 vocabulary |
| `ERR_PAYLOAD_INVALID` | Missing or invalid `payload` |
| `ERR_OPEN_URL_REQUIRED` | `open` action requires `payload.url` |

---

## Design Guarantees

This validator guarantees:

- **Fail-closed behavior**
- **No side effects**
- **No execution**
- **Deterministic results**
- **Protocol correctness over convenience**

If the input is invalid, the output is invalid. Always.

---

## Versioning

- This package implements **Orbit Protocol v1.0**
- Future protocol versions will be released as explicit updates
- Backward compatibility is never guessed

---

## License

MIT

---

## Project philosophy

Orbit is infrastructure.
Infrastructure should be boring, predictable, and hard to misuse.

This validator exists to make incorrect behavior impossible.