River

River is a command engine inspired by Brigadier, designed to run the same command definitions across frontend, backend, CLI, and MCP/skills.

Features

• Declarative command specs with literal and argument segments.
• Incremental parser and dispatcher.
• Token-level suggestions for autocomplete and tab-complete flows.
• Greedy arguments for Discord-style free text payloads.
• Named options/flags (--status done, -s done) with typed parsing.
• Fuzzy literal suggestions (typo tolerant).
• Default arguments: int, float, boolean, enum, rangeInt, rangeFloat.
• Default options: boolean, int, float, string.
• Backend reader to parse and dispatch command envelopes from API/queue/CLI.

Install

npm install @kyntocg/river

Quick Example

import {
  command,
  literal,
  argument,
  defaultArguments,
  enumSuggestions,
  dispatchCommand,
  RiverBackendReader,
} from "@kyntocg/river";

const specs = [
  command({
    id: "math.scale",
    description: "Scale values by numeric range",
    segments: [
      literal("scale"),
      argument("range", { parse: defaultArguments.rangeInt({ min: 1, max: 1000 }) }),
      argument("mode", {
        parse: defaultArguments.enum(["linear", "log"] as const),
        suggest: enumSuggestions(["linear", "log"] as const),
      }),
    ],
    execute: async (_ctx, args) => args,
  }),
];

await dispatchCommand("scale 10..50 linear", specs, {});

const reader = new RiverBackendReader(specs, (envelope) => ({ actorId: envelope.actorId }));
await reader.dispatch({ command: "scale 10..20 log", actorId: "u_123" });

Build Commands

npm install
npm run verify
npm run build
npm run typecheck
npm run pack:dry

Publish Flow

First-time setup

npm login

Release a new version

npm run release:patch
# or: npm run release:minor
# or: npm run release:major

Publish

npm run publish:public

Install In Killio Projects

Killio Frontend

cd ../Killio-Frontend
npm install @kyntocg/river

Killio Backend

cd ../Killio-Backend
npm install @kyntocg/river

Exports

• @kyntocg/river
  • Core: types, builders, tokenizer, parser, suggester, default arguments
  • Runtime: contracts, backend reader