@resolveio/server-lib 22.3.126 → 22.3.127

package/AGENTS.md

@@ -1,195 +0,0 @@
-# AGENTS.md
-
-## Infrastructure Guardrails
-
-- Never create, launch, provision, or clone a new EC2 instance unless the user explicitly asks for a new EC2 instance.
-- Disk pressure, full volumes, failed deploys, slow workers, or missing capacity are not permission to launch another EC2 instance; first clean unused files, inspect existing volumes, or ask before changing infrastructure.
-- If additional capacity is truly required, propose the smallest volume expansion or instance change and wait for explicit approval before acting.
-
-## Generated Method/Publications Files
-
-- Do not hand-edit generated Angular socket files such as `angular/app/methods.ts` or `angular/app/publications.ts`.
-- Change the real server method/publication definitions in `server/src/methods/` or `server/src/publications/` first.
-- After changing any method or publication signature, run `python3 methodAndPublicationListGenerator.py` from that project's `server/` directory.
-- Treat regeneration as required whenever server method/publication arguments change.
-
-## Overview
-resolveio-server-lib provides the backend infrastructure for the ResolveIO platform. It exposes server methods, publications, queues, and worker coordination so heavy work runs off the main thread.
-
-> Written for contributors and for GitHub Copilot / OpenAI Codex to learn the library.
-
----
-
-## Architecture
-resolveio-server-lib is a Node 22 / TypeScript library built on Mongo 8 (never use Mongoose). The core server connects through a custom Mongo wrapper and dispatches work to workers when clustered.
-
-### Directory Map
-```txt
-src/
-├─ collections/Mongo collection helpers
-├─ models/TypeScript interfaces & SimpleSchema
-├─ methods/loadXMethods() modules registering method handlers
-├─ publications/loadXPublications() modules registering subscriptions
-├─ managers/infrastructure managers (MethodManager, WebSocketManager, etc.)
-├─ cron/scheduled jobs
-├─ http/Express route helpers
-├─ util/shared utilities
-resolveio-server-app.tsbootstraps the server and connects to Mongo
-server-app.tsHTTP/WebSocket server for main & worker processes
-client-server-app.tsclient-facing entry for hybrid deployments
-```
-
-### Core Managers
-- MethodManager: registers method handlers via `methodManager.methods({ ... })`
-- SubscriptionManager: registers publications via `subscriptionManager.publications({ ... })`
-- WebSocketManager: tracks socket connections and emits messages
-- WorkerDispatcherManager & WorkerServerManager: queue and execute heavy jobs
-- CronManager: defines recurring jobs in `src/cron`
-- MongoManager & LocalLogManager: database and log helpers
-
-### Methods
-- Stateless functions invoked by clients.
-- Defined in `src/methods/*` using `loadXMethods` patterns.
-- Each method provides a `check` (SimpleSchema) and an async `function`.
-```ts
-export function loadFooMethods(methodManager: MethodManager) {
-	methodManager.methods({
-		doSomething: {
-			check: new SimpleSchema({ name: { type: String } }),
-			function: async function (name: string) {
-				// logic
-				return result;
-			},
-		},
-	});
-}
-```
-
-### Publications
-- Stream Mongo documents or computed data to subscribers.
-- Defined in `src/publications/*` using `loadXPublications`.
-- Publication objects declare `function`, optional `check`, and affected `collections`.
-```ts
-export function loadFlagsPublications(subscriptionManager: SubscriptionManager) {
-	subscriptionManager.publications({
-		flagWithType: {
-			function: (flagType: string) => Flags.findOne({ type: flagType }),
-			check: new SimpleSchema({ flagType: { type: String } }),
-			collections: ['flags'],
-		},
-	});
-}
-```
-
-### Worker & Queue Agents
-- Heavy or blocking work should be dispatched to worker servers.
-- Use `WorkerDispatcherManager.enqueue(task)` for background processing.
-- Cron jobs live in `src/cron` and register through `CronManager`.
-
----
-
-## Coding Conventions
-- Tabs for indentation, newline `else if`, opening brace on same line.
-- No `find` in loops; batch fetch then `bulkWrite`.
-- Separate validation, data retrieval, and processing blocks.
-- Use `async/await` with `try/catch`.
-- Never use `Math.round`; always use `round` from the ResolveIO client/server libraries.
-- Use `async/await` with `try/catch` instead of `.then()`/`.catch()`/`.finally()`.
-- Never leave unused variables, parameters, or imports; remove or refactor instead of suppressing lint.
-- Never construct Promises or use `.then()`/`.catch()`/`.finally()`; use `async/await` + `try/catch`.
-- Never leave promises floating; `await` or `return` every async call (including `Promise.all`).
-- Do not `await` inside `forEach`; use `for...of` or `Promise.all` with `map`.
-- Every async method must `await` at least one call (Mongo transactions).
-- Follow the `eslint.ts` rules.
-- Models and collections must mirror each other at all times.
-
-```ts
-if (x > 3) {
-	console.log(1);
-}
-else if (x === 2) {
-	console.log(2);
-}
-else {
-	console.log(3);
-}
-```
-
----
-
-## Formatting & Linting
-- `.editorconfig`, `.prettierrc.json`, and `.vscode/settings.json` enforce tabs and 120-column width.
-- Always open `eslint.config.js` in this project before coding and follow its rules; do not assume defaults from other repos.
-- Run lint before committing:
-```bash
-npx eslint .
-```
-
----
-
-## Quick Start
-```bash
-npm install
-npm run build
-npm start
-```
-
----
-
-## PR Checklist
-- Tabs only; `else`/`else if` start on new lines.
-- Avoid `find` in loops; use `bulkWrite`.
-- Use transactions when multiple writes must succeed atomically.
-- Offload heavy work to workers.
-- Run `npx eslint .` before committing.
-
----
-
-## Response Requirements
-
-- Include a customer-facing summary of the request and the estimated the number of human hours an advanced ResolveIO engineer would take to fully complete the task including testing.
-- Include a work ticket summary (what was done) and the estimated the number of human hours an advanced ResolveIO engineer would take to fully complete the task including testing.
-
----
-
-## Anti-Patterns
-- Converting tabs to spaces.
-- `updateOne` or `find` in loops.
-- Blocking work on the main server.
-- Deep nesting without early returns.
-
-## STRING _id POLICY
-- `_id` values are always strings in this codebase.
-- Generate `_id` values with `objectIdHexString()`.
-- Never use MongoDB `ObjectId` values or assumptions for `_id`.
-- For bulk writes (`insertMany`, `bulkWrite`, batch upserts), always set `_id` explicitly as a string before writing.
-- Never let MongoDB auto-generate `_id`, because that can create `ObjectId`-style ids.
-
-## RESOLVEIO LIBRARY SOURCE-OF-TRUTH POLICY
-- Never use `patch-package` for any `@resolveio/*` library changes.
-- Never patch `node_modules/@resolveio/*` as the primary fix path.
-- Always implement fixes in the actual source library repo (for example `resolveio-server-lib` or `resolveio-client-lib`).
-- When publishing a new `@resolveio/server-lib` version that ResolveIO apps should consume, update and push `ResolveIO/resolveio-libraries/system-package.json` before changing app `package.json` files or deploying. The deploy pipeline applies that overlay and will otherwise revert app package pins back to the old system version.
-- After applying a library-source fix, explicitly report:
-  - Why the fix had to be made in the library source (root cause and ownership).
-  - What downstream impact to expect (version bump/publish, consumer upgrades, rollout risk, and compatibility considerations).
-
-## AI Terminal Boundary Policy
-
-- Keep `resolveio-server-lib/src/methods/ai-terminal.ts` strictly platform-generic (`server-lib` / core ResolveIO only).
-- Do not add app-specific names, app-only aliases, app-specific field fallbacks, or app-specific branching logic in `server-lib` AI terminal code.
-- Put app-specific AI behavior in the app repo layer (for example `server/src/ai/assistant-heuristics.json` and app-level method/config wiring), not in `resolveio-server-lib`.
-
-## Distinct Filter Guidance
-
-- For list/filter dropdowns, use distinct-backed options from the underlying collection data wherever practical instead of hardcoded option lists.
-- Prefer list-template distinct filter support (`optionsDistinctKey`, `distinctQuery`, `distinctSort`, `distinctCollection`) when using `resolveio-list-template`.
-- Keep an explicit "All" option for optional filters and ensure labels/values map to the true stored field values.
-- Use hardcoded options only when values are truly fixed business enums that should not vary by dataset.
-
-## Rio Select Form-Control Rule
-
-- Never apply Bootstrap `form-control` to `rio-select` (including `class="form-control"`). Use component-specific classes for `rio-select` styling.
-- Never apply Bootstrap `form-control` to `rio-date-picker` (including `class="form-control"`). Use component-specific classes for `rio-date-picker` styling.
-
-- MongoDB `_id` values are strings in this codebase; do not use `ObjectId` types.

package/README.md

@@ -1,22 +0,0 @@
-## Copyright
-
-Copyright © 2017-2019 ResolveIO, LLC. All Rights Reserved. This work is to be used/viewed by ResolveIO, LLC Employees ONLY.
-
-## ResolveIO Command Line
-
-- `$ npm run server` - Run the server application.
-- `$ npm run build-prod` - Build production (dist folder).
-- `$ npm run package` - Build tarball for npm publish (version inside package json, must rebuild if changed)
-- `$ npm publish ./resolveio-server-lib-x.x.x.tgz` - Publish tarball to npm
-
-## Contents
-
-This package contains:
-
-- ResolveIO Server Library
-
-### Server
-
-The `server` folder contain single TypeScript (`.ts`) file which is the main file (`/server/src/index.ts`), and creates both connections to client-database and resolveio-support database, then creates the main server instance, and then starts it.
-
-All other server files should be located under `/server/src/*`.

package/build_package.sh

@@ -1,5 +0,0 @@
-#!/bin/bash
-source ~/.nvm/nvm.sh   # Ensure this path is correct for your nvm installation
-nvm use 22
-npm run build-prod
-npm pack ./dist

package/compileDTS.pl

@@ -1,64 +0,0 @@
-use strict;
-use warnings;
-use JSON;
-
-my @allIds;
-
-my $dir = './dist';
-
-my $extraFiles = '';
-
-search_dir($dir);
-
-sub search_dir {
-
-    my ($locdir) = @_;
-    # print "Entered search_dir sub, working with directory => $locdir \n";
-    my $dh; # handle
-
-    if ( !opendir ($dh, $locdir)) {
-        warn "Unable to open $locdir: $!\n";
-        return;
-    }
-    
-    my @FILES = grep { $_ ne '.' && $_ ne '..' } readdir($dh);
-        
-    foreach my $file (@FILES) {
-        my $path = "$locdir/$file";    
-        if ( -d $path ) {
-            # print "Directory $path found\n";
-            search_dir ($path); 
-        }
-        else {
-            if ($file =~ m/.d.ts/ and $file !~ m/index.d.ts/) {
-                # print "Open file $path\n";
-                open (FILE, "<", "$path");
-                my @lines = <FILE>;
-                close FILE;
-                chomp @lines;
-
-                for (my $k = 0; $k < scalar(@lines); $k++) {
-					if ($lines[$k] =~ m/^export / and $lines[$k] !~ m/export {};/) {
-						$extraFiles .= $lines[$k] . "\n";
-
-						if ($lines[$k] =~ m/\{\s*$/) {
-							while($lines[++$k] !~ m/^\};?\s*$/) {
-								$extraFiles .= $lines[$k] . "\n";
-							}
-
-							$extraFiles .= $lines[$k] . "\n";
-						}
-					}
-				}
-            }
-        }
-    }
-
-    closedir ($dh);
-}
-
-print "Extras\n\n$extraFiles";
-
-open (FILE, ">>", "./dist/index.d.ts");
-print FILE "\n$extraFiles";
-close FILE;

package/docs/ai-assistant-nightly-eval.md

@@ -1,65 +0,0 @@
-# AI Assistant Nightly Eval
-
-This repo now includes a scheduled workflow at:
-
-- `.github/workflows/ai-assistant-nightly-eval.yml`
-- `.github/workflows/ai-assistant-pr-guardrails.yml`
-
-It runs:
-
-1. `npm run ai-assistant-corpus-build`
-2. `npm run ai-assistant-data-parity-e2e`
-3. `npm run ai-assistant-corpus-replay-e2e`
-4. `npm run ai-assistant-eval-triage`
-
-Artifacts are uploaded from `tmp/` and the workflow summary includes top prioritized failure clusters.
-
-PR guardrails run on pull requests and execute:
-
-1. `npm run ai-assistant-utils-test`
-2. `npm run ai-assistant-routing-eval-test`
-
-## Required GitHub Setup
-
-Set the secret:
-
-- `OPENAI_API_KEY`
-
-Set repository variables (recommended):
-
-- `AI_ASSISTANT_EVAL_SERVER_DIR`: absolute path to server folder with settings and data access
-- `AI_ASSISTANT_EVAL_SETTINGS`: settings filename (default `settings.local.json`)
-- `AI_ASSISTANT_EVAL_APP_ID`: app id override (optional)
-- `AI_ASSISTANT_EVAL_USER_ID`: user id override for corpus replay/build (optional)
-- `AI_ASSISTANT_CODEX_MODEL`: model override (optional)
-
-## Running Manually
-
-Use **Actions -> AI Assistant Nightly Eval -> Run workflow**.
-
-Optional dispatch inputs:
-
-- `server_dir`
-- `settings_file`
-- `app_id`
-- `corpus_max_prompts`
-- `corpus_lookback_days`
-- `corpus_run_limit`
-- `codex_model`
-- `fail_on_eval_errors`
-
-## Output Files
-
-Main outputs:
-
-- `tmp/ai-assistant-query-corpus.json`
-- `tmp/ai-assistant-data-parity-e2e-output.json`
-- `tmp/ai-assistant-corpus-replay-e2e-output.json`
-- `tmp/ai-assistant-eval-triage.json`
-- `tmp/ai-assistant-eval-triage.md`
-
-The triage JSON now includes:
-
-- `allFailures.intentBuckets`
-- `allFailures.collectionBuckets`
-- `allFailures.priorityClusters`

package/docs/ai-assistant-preflight-checklist.md

@@ -1,23 +0,0 @@
-# AI Assistant Preflight Checklist
-
-Run this checklist before broader assistant evals.
-
-1. Lock deterministic runtime knobs in `settings.development.json`:
-- `AI_ASSISTANT_CODEX_PLANNER_ENABLED`
-- `AI_ASSISTANT_FAST_MODE_ENABLED`
-- `AI_ASSISTANT_ALWAYS_ALLOW_PROBE`
-- `AI_ASSISTANT_RUN_BUDGET_MS`
-- `AI_ASSISTANT_MONGO_MAX_TIME_MS`
-- `AI_ASSISTANT_CODEX_TIMEOUT_MS`
-
-2. Run focused assistant tests:
-- `npm run ai-assistant-utils-test`
-- `npm run ai-assistant-routing-eval-test`
-
-3. Validate the preflight prompt matrix:
-- `npm run ai-assistant-preflight-matrix`
-- Optional JSON output: `npm run ai-assistant-preflight-matrix -- --json`
-
-4. Use safe config copies when sharing logs/results:
-- Share `settings.development.redacted.json` (not `settings.development.json`)
-- Do not post raw secrets/tokens in issue comments or eval reports.

package/docs/ai-assistant-report-builder-bridge-playbook.md

@@ -1,115 +0,0 @@
-# AI Assistant Report Builder Bridge Playbook
-
-## Purpose
-This playbook defines how the ResolveIO AI assistant should fetch live data with high reliability.
-
-The assistant must not perform unrestricted collection access decisions.
-All data retrieval behavior is constrained by the Report Builder bridge contract:
-
-- `REPORT_BUILDER_READ` for list, detail, and simple count/total requests
-- `REPORT_BUILDER_AGG` for grouped summaries, trends, and ranked breakdowns
-
-## System Flow
-The runtime flow is:
-
-1. User asks a question.
-2. Assistant identifies if data is needed.
-3. Assistant resolves candidate collection and field names from context.
-4. Assistant emits one report-builder directive line.
-5. Server validates permission scope and collection eligibility.
-6. Server executes scoped read or aggregate with fallback logic.
-7. Server returns normalized table data.
-8. Assistant answers in plain language and includes a markdown table.
-
-## Bridge Guardrails
-The bridge enforces:
-
-- Permission checks using `permissionView`
-- Customer and client scoping for non-super-admin users
-- Invoice permission checks for invoice-like datasets
-- Disallowed operators (`$where`, `$function`, `$accumulator`) blocked
-- Collection eligibility limited to report-builder-enabled datasets (`useRB`)
-
-If a dataset is not report-builder-enabled, the request is rejected with a bridge error.
-
-## Querying Rules For the Assistant
-Use this sequence for every data request:
-
-1. Resolve intent type: list/detail vs grouped analytics.
-2. Resolve report style:
-- Dated report for any breakdown over time (daily/weekly/monthly/quarterly/yearly trends).
-- Grouped report for nested/grouped headers, grouped buckets, or grouped totals by dimensions.
-- List report for simple flat records without grouped or time-based bucketing.
-3. Resolve collection from route hints, user terms, and known field hints.
-4. Choose directive type:
-- Use `REPORT_BUILDER_READ` for snapshot rows, details, counts, or small totals.
-- Use `REPORT_BUILDER_AGG` for grouped sums/counts, trend lines, and rankings.
-5. Include `permissionView` in every directive.
-6. Keep query minimal:
-- add projection
-- add sort
-- add limit
-7. Enforce sort strategy:
-- Prefer ascending sort by popular keys when present: `name`, `company`, `item` (fallbacks: `title`, `label`, `customer`).
-- If no popular key exists, use stable fallback sort: `createdAt`/`date_created` then `_id`.
-8. Build filter logic intentionally:
-- Use `$and` for required constraints.
-- Use `$or` for alternative matches (name/company/item text patterns).
-9. Use advanced structures when needed:
-- Use custom fields for derived metrics (rates, percentages, margin, computed totals).
-- Use collection joins/lookups when selected fields span related collections.
-- If multiple arrays are selected, link arrays using shared identifiers (`_id` or `id_<x>`) to prevent duplicate/cartesian expansion.
-10. Use bounded relative dates (`<= $$NOW`) unless user requests future range.
-11. For empty result sets, run a tiny probe and fallback sequence before concluding no data.
-
-## Reliability Fallback Sequence
-When a query returns zero rows:
-
-1. Validate date field assumptions (`date_created`, `createdAt`, completion/paid fields).
-2. Run tiny probe (`limit 1-3`) to inspect field shape.
-3. Re-check name filters with tokenized regex.
-4. Apply id lookup fallback where `id_*` fields represent foreign keys.
-5. Retry collection mapping if a report/base partner collection is available.
-
-Only then report no matching data.
-
-## Response Contract
-After bridge execution:
-
-1. Give direct answer first.
-2. Add concise support bullets.
-3. Render markdown table.
-4. Never output raw JSON.
-5. Never claim certainty without successful tool response.
-
-## Directive Templates
-Read template:
-
-`REPORT_BUILDER_READ: {"collection":"<name>","query":{...},"options":{"projection":{...},"sort":{...},"limit":20},"permissionView":"</route>"}`
-
-Aggregate template:
-
-`REPORT_BUILDER_AGG: {"collection":"<name>","pipeline":[...],"options":{"allowDiskUse":true,"limit":20},"permissionView":"</route>"}`
-
-## Practical Examples
-Simple list:
-
-- User asks: "Show recent open work orders."
-- Tool: `REPORT_BUILDER_READ`
-- Query style: status filter + recent date range + sort desc + limit 20.
-
-Breakdown:
-
-- User asks: "Completed jobs by month for the last 6 months."
-- Tool: `REPORT_BUILDER_AGG`
-- Query style: bounded date range + completion status + group by month + sum/count.
-
-Revenue:
-
-- User asks: "Revenue this quarter."
-- Tool: `REPORT_BUILDER_AGG`
-- Query style: invoice dataset + paid/closed states + sum `paid_total` fallback `grand_total`.
-
-## Operational Note
-The internal server method names currently include `aiAssistantMongoRead` and `aiAssistantMongoAggregate`.
-These methods now operate under report-builder bridge constraints and are not unrestricted Mongo explorer paths.

package/eslint-plugin-custom/index.js

@@ -1,7 +0,0 @@
-// eslint-plugin-custom/index.js
-
-module.exports = {
-    rules: {
-      'no-filter-zero-index': require('./rules/no-filter-zero-index'),
-    },
-  };

package/eslint-plugin-custom/rules/no-filter-zero-index.js

@@ -1,44 +0,0 @@
-// eslint-plugin-custom/rules/no-filter-zero-index.js
-
-module.exports = {
-    meta: {
-      type: 'suggestion',
-      docs: {
-        description: 'Disallow using filter(...)[0] and suggest find(...) instead',
-        category: 'Best Practices',
-        recommended: false,
-      },
-      fixable: 'code',
-      messages: {
-        useFind: 'Please use `find` instead of `filter(...)[0]`.',
-      },
-    },
-    create(context) {
-      return {
-        MemberExpression(node) {
-          if (
-            node.property.type === 'Literal' &&
-            node.property.value === 0 &&
-            node.object.type === 'CallExpression' &&
-            node.object.callee.type === 'MemberExpression' &&
-            node.object.callee.property.name === 'filter'
-          ) {
-            context.report({
-              node,
-              messageId: 'useFind',
-              fix(fixer) {
-                const sourceCode = context.getSourceCode();
-                const filterCall = node.object;
-                const args = sourceCode.getText(filterCall.arguments[0]);
-                const objectText = sourceCode.getText(filterCall.callee.object);
-                return fixer.replaceText(
-                  node,
-                  `${objectText}.find(${args})`
-                );
-              },
-            });
-          }
-        },
-      };
-    },
-  };

package/eslint.config.js

@@ -1,103 +0,0 @@
-const tsParser = require('@typescript-eslint/parser');
-const typescriptPlugin = require('@typescript-eslint/eslint-plugin');
-const customPlugin = require('./eslint-plugin-custom');
-const promisePlugin = require('eslint-plugin-promise');
-
-module.exports = [
-  // Base configuration for all files
-  {
-    files: ['src/**/*.ts'],
-    ignores: [
-
-    ],
-    languageOptions: {
-      parser: tsParser,
-      // You can specify your TypeScript project here if needed
-      parserOptions: { project: './tsconfig.json' },
-    },
-    plugins: {
-      '@typescript-eslint': typescriptPlugin,
-      custom: customPlugin,
-      promise: promisePlugin
-    },
-    rules: {
-      "no-unused-vars": "error",
-      // Existing rule for Math.round
-      'no-restricted-properties': [
-        'error',
-        {
-          object: 'Math',
-          property: 'round',
-          message:
-            'Please use `round` from @resolveio/server-lib instead of Math.round.',
-        },
-      ],
-      // Existing rule to restrict imports from 'moment'
-      'no-restricted-imports': [
-        'error',
-        {
-          name: 'moment',
-          message: "Please use 'moment-timezone' instead of 'moment'.",
-        },
-      ],
-      "no-restricted-syntax": [
-        "error",
-        {
-          "selector": "NewExpression[callee.name='Promise']",
-          "message": "Use async/await instead of constructing new Promise."
-        },
-        {
-          "selector": "CallExpression[callee.property.name='then']",
-          "message": "Use async/await instead of .then()"
-        },
-        {
-          "selector": "CallExpression[callee.property.name='catch']",
-          "message": "Use try/catch with async/await instead of .catch()"
-        },
-        {
-          "selector": "CallExpression[callee.property.name='forEach'] ArrowFunctionExpression AwaitExpression",
-          "message": "Don't use await inside forEach. Use for...of instead."
-        }
-      ],
-      // New rule to disallow filter(...)[0]
-     'custom/no-filter-zero-index': 'error',
-     '@typescript-eslint/no-floating-promises': [
-				'error',
-				{
-					ignoreIIFE: false, // optional
-					ignoreVoid: false  // optional
-				}
-			],
-      '@typescript-eslint/require-await': 'error',
-      "no-throw-literal": "error",
-      "@typescript-eslint/await-thenable": "error",
-      "@typescript-eslint/no-misused-promises": [
-        "error",
-        {
-          "checksVoidReturn": {
-            "attributes": false,
-            "arguments": false,
-            "properties": false
-          }
-        }
-      ],
-      "promise/prefer-await-to-then": "error"
-    }
-  },
-  {
-    files: ['src/collections/**/*.ts'],
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: { project: './tsconfig.json' },
-    },
-    plugins: {
-      '@typescript-eslint': typescriptPlugin,
-      custom: customPlugin,
-      promise: promisePlugin,
-    },
-    rules: {
-      '@typescript-eslint/no-floating-promises': 'off', // Only change
-      // All other rules inherit from the base config
-    },
-  },
-];