@bernierllc/nevar-loop-controller 0.0.1 → 0.1.0

package/README.md

@@ -1,45 +1,86 @@
 # @bernierllc/nevar-loop-controller
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Runtime loop lifecycle management for the Nevar rules engine. Controls opt-in infinite loop execution with heartbeat monitoring and concurrency limits.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Installation
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @bernierllc/nevar-loop-controller
+```
 
-## Purpose
+## Usage
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@bernierllc/nevar-loop-controller`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```typescript
+import { LoopController } from '@bernierllc/nevar-loop-controller';
 
-## What is OIDC Trusted Publishing?
+const controller = new LoopController({
+  allowInfiniteLoops: true,
+  maxConcurrentLoops: 5,
+  heartbeatIntervalMs: 5000,
+  maxMissedHeartbeats: 3,
+});
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+// Check if loops are allowed
+if (controller.isAllowed()) {
+  const handle = controller.startLoop('order.monitor');
 
-## Setup Instructions
+  if (handle) {
+    // Send heartbeats during execution
+    controller.heartbeat(handle.id);
 
-To properly configure OIDC trusted publishing for this package:
+    // Inspect loop state
+    const state = controller.inspect(handle.id);
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+    // Pause/resume
+    controller.pause(handle.id);
+    controller.resume(handle.id);
 
-## DO NOT USE THIS PACKAGE
+    // Complete when done
+    controller.complete(handle.id);
+  }
+}
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+// Kill stale loops that missed heartbeats
+const killedIds = controller.checkHeartbeats();
 
-## More Information
+// List all active loops
+const active = controller.list();
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+## API
 
----
+### `LoopController`
 
-**Maintained for OIDC setup purposes only**
+Manages the lifecycle of opt-in infinite loops with heartbeat-based health monitoring.
+
+**Constructor:** `new LoopController(config?: Partial<LoopConfig>)`
+
+Default config: `allowInfiniteLoops: false`, `maxConcurrentLoops: 0`, `heartbeatIntervalMs: 5000`, `maxMissedHeartbeats: 3`
+
+- `isAllowed()` - Returns `true` if loops are enabled and concurrency limit is greater than zero
+- `startLoop(triggerKey)` - Creates a new loop handle. Returns `null` if loops are not allowed or at concurrency limit
+- `heartbeat(loopId)` - Records a heartbeat and increments iteration count. Returns `false` if loop not found or not running
+- `kill(loopId)` - Forcefully terminates a loop
+- `pause(loopId)` - Pauses a running loop
+- `resume(loopId)` - Resumes a paused loop
+- `complete(loopId)` - Marks a loop as completed
+- `list()` - Returns all active (running or paused) loop handles
+- `inspect(loopId)` - Returns the full `LoopHandle` for a given loop, or `null`
+- `checkHeartbeats()` - Kills loops that have missed too many heartbeats. Returns array of killed loop IDs
+- `getConfig()` - Returns a copy of the current configuration
+
+### `LoopControllerError`
+
+Error class for loop controller failures. Extends `Error` with `code` and `context` properties.
+
+## Integration Documentation
+
+### Logger Integration
+This package does not integrate with `@bernierllc/logger`. As a core package, logger integration is optional and not included by default. Consumers should handle logging at the service layer.
+
+### NeverHub Integration
+This package does not integrate with `@bernierllc/neverhub-adapter`. As a core package, NeverHub integration is not applicable. NeverHub registration should be handled by service-layer packages that compose this package.
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.

package/dist/errors.d.ts

@@ -0,0 +1 @@
+export { NevarLoopError as LoopControllerError } from '@bernierllc/nevar-types';

package/dist/errors.js

@@ -0,0 +1,12 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopControllerError = void 0;
+var nevar_types_1 = require("@bernierllc/nevar-types");
+Object.defineProperty(exports, "LoopControllerError", { enumerable: true, get: function () { return nevar_types_1.NevarLoopError; } });

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { LoopController } from './loop-controller';
+export { LoopControllerError } from './errors';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopControllerError = exports.LoopController = void 0;
+var loop_controller_1 = require("./loop-controller");
+Object.defineProperty(exports, "LoopController", { enumerable: true, get: function () { return loop_controller_1.LoopController; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "LoopControllerError", { enumerable: true, get: function () { return errors_1.LoopControllerError; } });

package/dist/loop-controller.d.ts

@@ -0,0 +1,18 @@
+import type { LoopConfig, LoopHandle } from '@bernierllc/nevar-types';
+export declare class LoopController {
+    private readonly config;
+    private readonly loops;
+    constructor(config?: Partial<LoopConfig>);
+    isAllowed(): boolean;
+    startLoop(triggerKey: string): LoopHandle | null;
+    heartbeat(loopId: string): boolean;
+    kill(loopId: string): boolean;
+    pause(loopId: string): boolean;
+    resume(loopId: string): boolean;
+    complete(loopId: string): boolean;
+    list(): LoopHandle[];
+    inspect(loopId: string): LoopHandle | null;
+    checkHeartbeats(): string[];
+    getConfig(): LoopConfig;
+    private getActiveLoops;
+}

package/dist/loop-controller.js

@@ -0,0 +1,123 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopController = void 0;
+const crypto_1 = require("crypto");
+const DEFAULT_CONFIG = {
+    allowInfiniteLoops: false,
+    maxConcurrentLoops: 0,
+    heartbeatIntervalMs: 5000,
+    maxMissedHeartbeats: 3,
+};
+class LoopController {
+    config;
+    loops = new Map();
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    isAllowed() {
+        return !!this.config.allowInfiniteLoops && (this.config.maxConcurrentLoops ?? 0) > 0;
+    }
+    startLoop(triggerKey) {
+        if (!this.isAllowed()) {
+            return null;
+        }
+        const activeCount = this.getActiveLoops().length;
+        if (activeCount >= this.config.maxConcurrentLoops) {
+            return null;
+        }
+        const now = new Date();
+        const handle = {
+            id: (0, crypto_1.randomUUID)(),
+            triggerKey,
+            startedAt: now,
+            iterations: 0,
+            status: 'running',
+            lastHeartbeat: now,
+        };
+        this.loops.set(handle.id, handle);
+        return handle;
+    }
+    heartbeat(loopId) {
+        const handle = this.loops.get(loopId);
+        if (!handle || handle.status !== 'running') {
+            return false;
+        }
+        handle.lastHeartbeat = new Date();
+        handle.iterations = (handle.iterations ?? 0) + 1;
+        return true;
+    }
+    kill(loopId) {
+        const handle = this.loops.get(loopId);
+        if (!handle) {
+            return false;
+        }
+        handle.status = 'killed';
+        return true;
+    }
+    pause(loopId) {
+        const handle = this.loops.get(loopId);
+        if (!handle || handle.status !== 'running') {
+            return false;
+        }
+        handle.status = 'paused';
+        return true;
+    }
+    resume(loopId) {
+        const handle = this.loops.get(loopId);
+        if (!handle || handle.status !== 'paused') {
+            return false;
+        }
+        handle.status = 'running';
+        return true;
+    }
+    complete(loopId) {
+        const handle = this.loops.get(loopId);
+        if (!handle) {
+            return false;
+        }
+        handle.status = 'completed';
+        return true;
+    }
+    list() {
+        return this.getActiveLoops();
+    }
+    inspect(loopId) {
+        return this.loops.get(loopId) ?? null;
+    }
+    checkHeartbeats() {
+        const now = Date.now();
+        const threshold = this.config.heartbeatIntervalMs * this.config.maxMissedHeartbeats;
+        const killedIds = [];
+        for (const handle of this.loops.values()) {
+            if (handle.status !== 'running') {
+                continue;
+            }
+            const elapsed = now - handle.lastHeartbeat.getTime();
+            if (elapsed > threshold) {
+                handle.status = 'killed';
+                killedIds.push(handle.id);
+            }
+        }
+        return killedIds;
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getActiveLoops() {
+        const active = [];
+        for (const handle of this.loops.values()) {
+            if (handle.status === 'running' || handle.status === 'paused') {
+                active.push(handle);
+            }
+        }
+        return active;
+    }
+}
+exports.LoopController = LoopController;

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "@bernierllc/nevar-loop-controller",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @bernierllc/nevar-loop-controller",
+  "version": "0.1.0",
+  "description": "Supervised loop management with heartbeat monitoring for the Nevar rules engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "nevar",
+    "rules-engine",
+    "loop-controller",
+    "heartbeat",
+    "supervised-loops"
+  ],
+  "author": "Bernier LLC",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bernierllc/tools.git",
+    "directory": "packages/core/nevar-loop-controller"
+  },
+  "dependencies": {
+    "@bernierllc/nevar-types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prebuild": "npm run clean",
+    "clean": "rimraf dist",
+    "test": "jest",
+    "test:run": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src __tests__ --ext .ts"
+  }
+}