covenant-protocol 0.1.0

package/gcode-protocol.d.ts

@@ -0,0 +1,55 @@
+/**
+ * G-Code Protocol Definition
+ *
+ * Defines the typed contract for G-Code parsing using LinuxCNC's rs274ngc interpreter.
+ */
+
+import type { ChannelProtocol } from "@edenapp/types";
+import type { GCodeParseResult, ParseProgress } from "@linuxcnc-node/types";
+
+// ============================================================================
+// G-Code Types (re-export for convenience)
+// ============================================================================
+
+export type { GCodeParseResult, ParseProgress };
+
+// ============================================================================
+// Protocol Definition
+// ============================================================================
+
+/**
+ * Protocol for G-Code parsing over AppBus.
+ */
+export interface GCodeProtocol extends ChannelProtocol {
+  hostMessages: {
+    /** Parse progress update */
+    "parse-progress": ParseProgress;
+
+    /** Error occurred */
+    error: {
+      code: string;
+      message: string;
+    };
+  };
+
+  peerMessages: {};
+
+  hostHandles: {
+    /** Parse a G-code file */
+    parse: {
+      args: {
+        filepath: string;
+        iniPath: string;
+        progressUpdates?: number;
+      };
+      result: GCodeParseResult;
+    };
+
+    ping: {
+      args: {};
+      result: { timestamp: number };
+    };
+  };
+
+  peerHandles: {};
+}

package/hal-protocol.d.ts

@@ -0,0 +1,285 @@
+/**
+ * HAL Protocol Definition
+ *
+ * Defines the typed contract for HAL (Hardware Abstraction Layer) communication.
+ *
+ * This protocol enables real-time monitoring and control of LinuxCNC HAL.
+ */
+
+import type { ChannelProtocol } from "@edenapp/types";
+import type {
+  HalType,
+  HalPinDir,
+  HalParamDir,
+  RtapiMsgLevel,
+  HalPinInfo,
+  HalParamInfo,
+  HalSignalInfo,
+} from "@linuxcnc-node/types";
+
+// ============================================================================
+// HAL Types (re-export for convenience)
+// ============================================================================
+
+export type {
+  HalType,
+  HalPinDir,
+  HalParamDir,
+  RtapiMsgLevel,
+  HalPinInfo,
+  HalParamInfo,
+  HalSignalInfo,
+};
+
+export type HalValue = boolean | number;
+
+/** Delta update structure for HAL items */
+export interface HalDelta {
+  /** Changed items as flat array of name-value pairs */
+  changes: Array<{ name: string; value: HalValue }>;
+  /** Monotonic cursor for sync verification */
+  cursor: number;
+  /** Timestamp of update */
+  timestamp: number;
+}
+
+// ============================================================================
+// Protocol Definition
+// ============================================================================
+/**
+ * Protocol for HAL communication over AppBus.
+ *
+ * Host = HAL service provider (manages HAL component)
+ * Peer = HAL service consumer (controls/monitors HAL)
+ *
+ * Each connection is bound to a single HAL component. The component is created
+ * when component/init is called and disposed when the connection closes.
+ */
+export interface HalProtocol extends ChannelProtocol {
+  // -------------------------------------------------------------------------
+  // Messages sent by host, received by peer
+  // -------------------------------------------------------------------------
+  hostMessages: {
+    /** HAL component is ready */
+    "hal-ready": {
+      componentName: string;
+      prefix: string;
+    };
+
+    /** Flat delta: only changed items with their new values */
+    "items-delta": HalDelta;
+
+    /** Error occurred in backend */
+    error: {
+      code: string;
+      message: string;
+    };
+  };
+
+  // -------------------------------------------------------------------------
+  // Messages sent by peer, received by host
+  // -------------------------------------------------------------------------
+  peerMessages: {};
+
+  // -------------------------------------------------------------------------
+  // Requests that peer sends, host handles
+  // -------------------------------------------------------------------------
+  hostHandles: {
+    // Component Operations (bound to this connection)
+    /** Initialize the HAL component for this connection. Must be called first. */
+    "component/init": {
+      args: { name: string; prefix?: string };
+      result: { success: boolean; componentName: string; error?: string };
+    };
+
+    /** Mark the bound component as ready */
+    "component/ready": {
+      args: {};
+      result: { success: boolean; error?: string };
+    };
+
+    /** Mark the bound component as not ready */
+    "component/unready": {
+      args: {};
+      result: { success: boolean; error?: string };
+    };
+
+    /** Create a pin on the bound component */
+    "pin/create": {
+      args: {
+        name: string;
+        type: HalType;
+        direction: HalPinDir;
+      };
+      result: { success: boolean; fullName: string; error?: string };
+    };
+
+    /** Create a parameter on the bound component */
+    "param/create": {
+      args: {
+        name: string;
+        type: HalType;
+        direction: HalParamDir;
+      };
+      result: { success: boolean; fullName: string; error?: string };
+    };
+
+    /** Get value of a pin or parameter on the bound component */
+    "item/get-value": {
+      args: { name: string };
+      result: { value: HalValue };
+    };
+
+    /** Set value of a pin or parameter on the bound component */
+    "item/set-value": {
+      args: { name: string; value: HalValue };
+      result: { success: boolean; error?: string };
+    };
+
+    /**
+     * Get all current item values.
+     * @returns All item values plus current cursor
+     */
+    "items/sync": {
+      args: {};
+      result: {
+        /** All current item values */
+        items: Record<string, HalValue>;
+        /** Current cursor for delta updates */
+        cursor: number;
+      };
+    };
+
+    // =========================================================================
+    // GLOBAL: System-wide HAL operations (not tied to bound component)
+    // =========================================================================
+
+    /** Check if any component exists by name */
+    "global/component-exists": {
+      args: { componentName: string };
+      result: { exists: boolean };
+    };
+
+    /** Check if any component is ready by name */
+    "global/component-is-ready": {
+      args: { componentName: string };
+      result: { ready: boolean };
+    };
+
+    /** Create a new HAL signal */
+    "global/signal-create": {
+      args: { name: string; type: HalType };
+      result: { success: boolean; error?: string };
+    };
+
+    /** Get value of any signal by name */
+    "global/signal-get-value": {
+      args: { signalName: string };
+      result: { value: HalValue };
+    };
+
+    /** Set value of any signal by name */
+    "global/signal-set-value": {
+      args: { signalName: string; value: HalValue };
+      result: { success: boolean; error?: string };
+    };
+
+    /** Connect any pin to a signal */
+    "global/signal-connect": {
+      args: { pinName: string; signalName: string };
+      result: { success: boolean; error?: string };
+    };
+
+    /** Disconnect any pin from its signal */
+    "global/signal-disconnect": {
+      args: { pinName: string };
+      result: { success: boolean; error?: string };
+    };
+
+    /** Check if any pin has a writer */
+    "global/pin-has-writer": {
+      args: { pinName: string };
+      result: { hasWriter: boolean };
+    };
+
+    /** Get value of any pin, param, or signal by full name */
+    "global/get-value": {
+      args: { name: string };
+      result: { value: HalValue; type: "pin" | "param" | "signal" };
+    };
+
+    /** List all pins in HAL */
+    "global/list-pins": {
+      args: { filter?: string };
+      result: { pins: HalPinInfo[] };
+    };
+
+    /** List all parameters in HAL */
+    "global/list-params": {
+      args: { filter?: string };
+      result: { params: HalParamInfo[] };
+    };
+
+    /** List all signals in HAL */
+    "global/list-signals": {
+      args: { filter?: string };
+      result: { signals: HalSignalInfo[] };
+    };
+
+    /** List all pins, params, and signals in HAL */
+    "global/list-all": {
+      args: {};
+      result: {
+        pins: HalPinInfo[];
+        params: HalParamInfo[];
+        signals: HalSignalInfo[];
+      };
+    };
+
+    /** Get RTAPI message level */
+    "global/msg-level-get": {
+      args: {};
+      result: { level: RtapiMsgLevel };
+    };
+
+    /** Set RTAPI message level */
+    "global/msg-level-set": {
+      args: { level: RtapiMsgLevel };
+      result: { success: boolean; previousLevel: RtapiMsgLevel };
+    };
+
+    // =========================================================================
+    // CONNECTION: Status and health for this connection
+    // =========================================================================
+
+    /** Health check */
+    ping: {
+      args: {};
+      result: { timestamp: number };
+    };
+
+    /** Get backend status for this connection */
+    "get-status": {
+      args: {};
+      result: {
+        connected: boolean;
+        componentName: string;
+        componentReady: boolean;
+        pinCount: number;
+        paramCount: number;
+        uptime: number;
+      };
+    };
+  };
+
+  // -------------------------------------------------------------------------
+  // Requests that host sends, peer handles
+  // -------------------------------------------------------------------------
+  peerHandles: {
+    /** Host requests peer to confirm it's alive */
+    "health-check": {
+      args: {};
+      result: { alive: boolean; timestamp: number };
+    };
+  };
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./gcode-protocol";
+export * from "./hal-protocol";
+export * from "./linuxcnc-protocol";
+export * from "./position-logger-protocol";

package/linuxcnc-protocol.d.ts

@@ -0,0 +1,444 @@
+/**
+ * LinuxCNC Core Protocol Definition
+ *
+ * Defines the typed contract for LinuxCNC communication over AppBus.
+ * Wraps StatChannel, CommandChannel, and ErrorChannel.
+ */
+
+import type { ChannelProtocol } from "@edenapp/types";
+import type {
+  LinuxCNCStat,
+  LinuxCNCStatPaths,
+  LinuxCNCError,
+  RcsStatus,
+  TaskMode,
+  TaskState,
+  TrajMode,
+  DebugFlags,
+  ToolEntry,
+  RecursivePartial,
+  StatChange,
+} from "@linuxcnc-node/types";
+
+// ============================================================================
+// Types (re-export for convenience)
+// ============================================================================
+
+export type {
+  LinuxCNCStat,
+  LinuxCNCStatPaths,
+  LinuxCNCError,
+  RcsStatus,
+  TaskMode,
+  TaskState,
+  TrajMode,
+  DebugFlags,
+  ToolEntry,
+  StatChange,
+};
+
+// ============================================================================
+// Protocol Definition
+// ============================================================================
+
+/**
+ * Protocol for LinuxCNC core operations over AppBus.
+ */
+export interface LinuxCNCProtocol extends ChannelProtocol {
+  hostMessages: {
+    /** Flat delta: only changed paths with their new values */
+    "stat-delta": {
+      /** Changed paths and values */
+      changes: StatChange[];
+      /** Monotonic cursor for sync verification */
+      cursor: number;
+      timestamp: number;
+    };
+
+    /** Error/message from LinuxCNC */
+    "error-channel-event": LinuxCNCError;
+
+    /** Backend error */
+    error: {
+      code: string;
+      message: string;
+    };
+  };
+
+  peerMessages: {};
+
+  hostHandles: {
+    // =========================================================================
+    // STAT: Status monitoring
+    // =========================================================================
+
+    /**
+     * Get full LinuxCNC stat snapshot.
+     * @returns Full stat plus current cursor
+     */
+    "stat/sync": {
+      args: {};
+      result: {
+        stat: LinuxCNCStat;
+        cursor: number;
+      };
+    };
+
+    /** Get specific stat value by path */
+    "stat/get-value": {
+      args: { path: LinuxCNCStatPaths };
+      result: { value: unknown };
+    };
+
+    // =========================================================================
+    // COMMAND: Task control
+    // =========================================================================
+
+    /** Set task mode (MDI, MANUAL, AUTO) */
+    "cmd/set-task-mode": {
+      args: { mode: TaskMode };
+      result: RcsStatus;
+    };
+
+    /** Set machine state (ESTOP, ESTOP_RESET, OFF, ON) */
+    "cmd/set-state": {
+      args: { state: TaskState };
+      result: RcsStatus;
+    };
+
+    /** Execute MDI command */
+    "cmd/mdi": {
+      args: { command: string };
+      result: RcsStatus;
+    };
+
+    /** Abort current task */
+    "cmd/abort": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Sync VAR file to disk */
+    "cmd/task-plan-synch": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Reset G-code interpreter */
+    "cmd/reset-interpreter": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Program control
+    // =========================================================================
+
+    /** Open G-code program file */
+    "cmd/program-open": {
+      args: { filePath: string };
+      result: RcsStatus;
+    };
+
+    /** Run program from line */
+    "cmd/program-run": {
+      args: { startLine?: number };
+      result: RcsStatus;
+    };
+
+    /** Pause program execution */
+    "cmd/program-pause": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Resume paused program */
+    "cmd/program-resume": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Step one line */
+    "cmd/program-step": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Reverse execution direction */
+    "cmd/program-reverse": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Forward execution direction */
+    "cmd/program-forward": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Motion control
+    // =========================================================================
+
+    /** Set feedrate override scale (1.0 = 100%) */
+    "cmd/set-feed-rate": {
+      args: { scale: number };
+      result: RcsStatus;
+    };
+
+    /** Set rapid override scale (1.0 = 100%) */
+    "cmd/set-rapid-rate": {
+      args: { scale: number };
+      result: RcsStatus;
+    };
+
+    /** Set max trajectory velocity */
+    "cmd/set-max-velocity": {
+      args: { velocity: number };
+      result: RcsStatus;
+    };
+
+    /** Set trajectory mode (FREE, COORD, TELEOP) */
+    "cmd/set-traj-mode": {
+      args: { mode: TrajMode };
+      result: RcsStatus;
+    };
+
+    /** Enable/disable teleop mode */
+    "cmd/teleop-enable": {
+      args: { enable: boolean };
+      result: RcsStatus;
+    };
+
+    /** Enable/disable feedrate override */
+    "cmd/set-feed-override-enable": {
+      args: { enable: boolean };
+      result: RcsStatus;
+    };
+
+    /** Enable/disable feed hold */
+    "cmd/set-feed-hold-enable": {
+      args: { enable: boolean };
+      result: RcsStatus;
+    };
+
+    /** Enable/disable adaptive feed */
+    "cmd/set-adaptive-feed-enable": {
+      args: { enable: boolean };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Jogging
+    // =========================================================================
+
+    /** Start continuous jog */
+    "cmd/jog-continuous": {
+      args: { axis: number; speed: number; isJoint?: boolean };
+      result: RcsStatus;
+    };
+
+    /** Jog a fixed increment */
+    "cmd/jog-increment": {
+      args: {
+        axis: number;
+        speed: number;
+        increment: number;
+        isJoint?: boolean;
+      };
+      result: RcsStatus;
+    };
+
+    /** Stop jogging */
+    "cmd/jog-stop": {
+      args: { axis: number; isJoint?: boolean };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Homing
+    // =========================================================================
+
+    /** Home a joint (-1 for all) */
+    "cmd/home": {
+      args: { joint: number };
+      result: RcsStatus;
+    };
+
+    /** Unhome a joint (-1 for all) */
+    "cmd/unhome": {
+      args: { joint: number };
+      result: RcsStatus;
+    };
+
+    /** Set joint min position limit */
+    "cmd/set-min-position-limit": {
+      args: { joint: number; limit: number };
+      result: RcsStatus;
+    };
+
+    /** Set joint max position limit */
+    "cmd/set-max-position-limit": {
+      args: { joint: number; limit: number };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Spindle
+    // =========================================================================
+
+    /** Turn spindle on at RPM (positive=CW, negative=CCW) */
+    "cmd/spindle-on": {
+      args: { speed: number; spindle?: number; wait?: boolean };
+      result: RcsStatus;
+    };
+
+    /** Turn spindle off */
+    "cmd/spindle-off": {
+      args: { spindle?: number };
+      result: RcsStatus;
+    };
+
+    /** Set spindle override scale (1.0 = 100%) */
+    "cmd/spindle-override": {
+      args: { scale: number; spindle?: number };
+      result: RcsStatus;
+    };
+
+    /** Engage/release spindle brake */
+    "cmd/spindle-brake": {
+      args: { engage: boolean; spindle?: number };
+      result: RcsStatus;
+    };
+
+    /** Increase spindle speed */
+    "cmd/spindle-increase": {
+      args: { spindle?: number };
+      result: RcsStatus;
+    };
+
+    /** Decrease spindle speed */
+    "cmd/spindle-decrease": {
+      args: { spindle?: number };
+      result: RcsStatus;
+    };
+
+    /** Enable/disable spindle override */
+    "cmd/set-spindle-override-enable": {
+      args: { enable: boolean; spindle?: number };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Coolant
+    // =========================================================================
+
+    /** Turn mist coolant on/off */
+    "cmd/set-mist": {
+      args: { on: boolean };
+      result: RcsStatus;
+    };
+
+    /** Turn flood coolant on/off */
+    "cmd/set-flood": {
+      args: { on: boolean };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Tool
+    // =========================================================================
+
+    /** Reload tool table from disk */
+    "cmd/load-tool-table": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Set tool data */
+    "cmd/set-tool": {
+      args: { tool: RecursivePartial<ToolEntry> & { toolNo: number } };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: I/O
+    // =========================================================================
+
+    /** Set digital output pin */
+    "cmd/set-digital-output": {
+      args: { index: number; value: boolean };
+      result: RcsStatus;
+    };
+
+    /** Set analog output value */
+    "cmd/set-analog-output": {
+      args: { index: number; value: number };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // COMMAND: Misc
+    // =========================================================================
+
+    /** Override soft limits for recovery */
+    "cmd/override-limits": {
+      args: {};
+      result: RcsStatus;
+    };
+
+    /** Enable/disable optional stop (M1) */
+    "cmd/set-optional-stop": {
+      args: { enable: boolean };
+      result: RcsStatus;
+    };
+
+    /** Enable/disable block delete (/) */
+    "cmd/set-block-delete": {
+      args: { enable: boolean };
+      result: RcsStatus;
+    };
+
+    /** Set debug flags */
+    "cmd/set-debug-level": {
+      args: { level: DebugFlags };
+      result: RcsStatus;
+    };
+
+    /** Send error to operator display */
+    "cmd/send-operator-error": {
+      args: { message: string };
+      result: RcsStatus;
+    };
+
+    /** Send text to operator display */
+    "cmd/send-operator-text": {
+      args: { message: string };
+      result: RcsStatus;
+    };
+
+    /** Send message to operator display */
+    "cmd/send-operator-display": {
+      args: { message: string };
+      result: RcsStatus;
+    };
+
+    // =========================================================================
+    // CONNECTION
+    // =========================================================================
+
+    /** Health check */
+    ping: {
+      args: {};
+      result: { timestamp: number };
+    };
+  };
+
+  peerHandles: {
+    /** Host requests peer to confirm it's alive */
+    "health-check": {
+      args: {};
+      result: { alive: boolean; timestamp: number };
+    };
+  };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "covenant-protocol",
+  "version": "0.1.0",
+  "description": "Protocol definitions for communicating with LinuxCNC through Eden's AppBus",
+  "types": "index.d.ts",
+  "scripts": {},
+  "author": "Dariusz Majnert",
+  "license": "MIT",
+  "dependencies": {
+    "@edenapp/types": "^0.2.1",
+    "@linuxcnc-node/types": "^2.1.1"
+  },
+  "peerDependencies": {
+    "typescript": "*"
+  },
+  "files": [
+    "*.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "covenant",
+    "protocol",
+    "ipc",
+    "linuxcnc",
+    "hal",
+    "typescript"
+  ]
+}

package/position-logger-protocol.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Position Logger Protocol Definition
+ *
+ * Defines the typed contract for machine position logging and streaming.
+ * Used for toolpath visualization and motion history.
+ */
+
+import type { ChannelProtocol } from "@edenapp/types";
+import type { PositionLoggerIndex } from "@linuxcnc-node/types";
+
+// ============================================================================
+// Types (re-export for convenience)
+// ============================================================================
+
+export type { PositionLoggerIndex };
+
+// Note: POSITION_STRIDE constant should be imported directly from @linuxcnc-node/types
+
+// ============================================================================
+// Protocol Definition
+// ============================================================================
+
+/**
+ * Protocol for position logging over AppBus.
+ *
+ * Tracks machine tool path over time. All positions are returned as Float64Array
+ * with 10 elements per point: [x, y, z, a, b, c, u, v, w, motionType]
+ *
+ * Use PositionLoggerIndex enum and POSITION_STRIDE constant for array access.
+ */
+export interface PositionLoggerProtocol extends ChannelProtocol {
+  hostMessages: {
+    /**
+     * Delta position update (pushed at configured interval)
+     * Contains only NEW points since the last update for this connection.
+     */
+    "position-update": {
+      /** New points since last update (Float64Array with POSITION_STRIDE per point) */
+      points: Float64Array;
+      /** Number of new points in this update */
+      count: number;
+      /** Server-side cursor after this update (monotonic, for sync verification) */
+      cursor: number;
+    };
+
+    /** Backend error */
+    error: {
+      code: string;
+      message: string;
+    };
+  };
+
+  peerMessages: {};
+
+  hostHandles: {
+    /**
+     * Start position logging
+     * @param interval - Logging interval in seconds (default: 0.01)
+     * @param maxHistory - Maximum number of points to keep in history (default: 10000)
+     */
+    start: {
+      args: { interval?: number; maxHistory?: number };
+      result: { success: boolean; cursor: number };
+    };
+
+    /** Stop position logging */
+    stop: {
+      args: {};
+      result: { success: boolean };
+    };
+
+    /** Clear the position history (invalidates all previous cursors) */
+    clear: {
+      args: {};
+      result: { success: boolean };
+    };
+
+    /**
+     * Get full position history.
+     * @returns Complete history as Float64Array plus point count and cursor
+     */
+    sync: {
+      args: {};
+      result: {
+        /** Full position history */
+        history: Float64Array;
+        /** Number of points in history */
+        count: number;
+        /** Current cursor for delta updates */
+        cursor: number;
+      };
+    };
+
+    /**
+     * Get the current position as a Float64Array
+     * Layout: [x, y, z, a, b, c, u, v, w, motionType]
+     * @returns Float64Array with 10 values, or null if no position available
+     */
+    "get-current": {
+      args: {};
+      result: { position: Float64Array | null };
+    };
+
+    /** Get current cursor position without any data */
+    "get-cursor": {
+      args: {};
+      result: { cursor: number };
+    };
+
+    /** Health check */
+    ping: {
+      args: {};
+      result: { timestamp: number };
+    };
+  };
+
+  peerHandles: {};
+}