@resolveio/server-lib 22.3.221 → 22.3.223

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
-    },
-  },
-];

package/gulpfile.js

@@ -1,216 +0,0 @@
-var gulp = require("gulp");
-var exec = require('child_process').exec;
-var rename = require("gulp-rename");
-var del = require('del');
-var sourcemaps = require('gulp-sourcemaps');
-var zip = require('gulp-zip');
-var ts = require("gulp-typescript");
-var nodemon = require("gulp-nodemon");
-var uglify = require('gulp-uglify');
-var gulpIf = require('gulp-if');
-const { ESLint } = require('eslint');
-const fs = require('fs');
-
-
-var paths = {
-    src: 'src/**/*',
-    srcTS: 'src/**/*.ts',
-    srcPrivate: 'src/private/**/*',
-
-    tmp: 'tmp',
-    tmpJS: 'tmp/**/*.js',
-    tmpPrivate: 'tmp/private',
-
-    dist: 'dist',
-    distJS: 'dist/**/*.js',
-    distPrivate: 'dist/private',
-
-    dbDir: 'mongo/data/db',
-    dbLogs: 'mongo/log'
-};
-var shell = require('gulp-shell');
-
-gulp.task('eslint', async function () {
-    const eslint = new ESLint({
-      overrideConfigFile: './eslint.config.js'
-    });
-  
-    const results = await eslint.lintFiles(['./src/**/*.ts']);
-    const formatter = await eslint.loadFormatter('stylish');
-    const resultText = formatter.format(results);
-  
-    console.log(resultText);
-  
-    const hasErrors = results.some(result => result.errorCount > 0);
-  
-    if (hasErrors) {
-      throw new Error('ESLint errors detected');
-    }
-});
-
-gulp.task('clean', function () {
-    return del([paths.tmp, paths.dist]);
-});
-
-// Function to check if MongoDB is running and kill the process if it is
-function killMongoIfRunning(cb) {
-    exec('pgrep mongod', (err, stdout, stderr) => {
-        if (stdout) {
-            console.log('MongoDB is running. Killing the process...');
-            exec('pkill mongod', (killErr, killStdout, killStderr) => {
-                if (killErr) {
-                    console.error('Error killing MongoDB:', killStderr);
-                } else {
-                    console.log('MongoDB process killed.');
-                }
-                cb();
-            });
-        } else {
-            console.log('MongoDB is not running.');
-            cb();
-        }
-    });
-}
-
-// Gulp task to start MongoDB after killing any existing process
-gulp.task('mongo-start', function(done) {
-    killMongoIfRunning(() => {
-        fs.mkdirSync(paths.dbDir, { recursive: true });
-        fs.mkdirSync(paths.dbLogs, { recursive: true });
-
-        const finish = (() => {
-            let completed = false;
-            return (err) => {
-                if (completed) {
-                    return;
-                }
-
-                completed = true;
-                done(err);
-            };
-        })();
-
-        const stream = gulp.src('.')
-            .pipe(shell('mongod --fork --dbpath ' + paths.dbDir + '/ --logpath ' + paths.dbLogs + '/mongo.log --port 3001 --replSet rs0 --bind_ip 127.0.0.1'))
-            .pipe(shell(['mongosh --port 3001 < mongodbensurers.js']));
-
-        stream.on('error', finish);
-        stream.on('end', () => finish());
-        stream.on('finish', () => finish());
-    });
-});
-  
-gulp.task("mongo-stop", function() {
-    return gulp.src('.')
-        .pipe(shell(['killall mongod']));
-});
-
-gulp.task("config", gulp.series("clean", function() {
-    return gulp.src('./settings.development.json')
-        .pipe(rename('settings.json'))
-        .pipe(gulp.dest(paths.tmp));
-}));
-
-gulp.task("email-templates", function() {
-    return gulp.src(paths.srcPrivate)
-        .pipe(gulp.dest(paths.tmpPrivate));
-});
-
-function waitForStreams(streams) {
-	return Promise.all(streams.map((stream) => {
-		return new Promise((resolve, reject) => {
-			stream.on('finish', resolve);
-			stream.on('end', resolve);
-			stream.on('error', reject);
-		});
-	}));
-}
-
-function buildTypeScript(destination) {
-	var tsProject = ts.createProject("tsconfig.json");
-	var tsResult = gulp.src('src/**/*.ts')
-		.pipe(sourcemaps.init())
-		.pipe(tsProject());
-
-	var jsStream = tsResult.js
-		.pipe(sourcemaps.mapSources((sourcePath) => {
-			return sourcePath;
-		}))
-		.pipe(sourcemaps.write("./"))
-		.pipe(gulp.dest(destination));
-
-	var dtsStream = tsResult.dts.pipe(gulp.dest(destination));
-
-	return waitForStreams([jsStream, dtsStream]);
-}
-
-gulp.task("compile", function () {
-	return buildTypeScript(paths.tmp);
-});
-
-gulp.task('watch', function (done) {
-    gulp.watch([paths.src, './node_modules'], gulp.series('compile'));
-
-    done();
-});
-
-gulp.task("default", gulp.parallel(gulp.series("config", "email-templates", 'compile', (done) => {
-    nodemon({
-        script: "tmp/client-server-app.js",
-        watch: "tmp",
-        // exec: 'node --inspect-brk --max-old-space-size=1800 --trace-warnings',
-        exec: 'node --inspect --max-old-space-size=1800 --trace-warnings',
-        delay: 500
-    });
-
-    done();
-}), 'watch'));
-
-gulp.task("config:dist", gulp.series("clean", function() {
-	const configPath = fs.existsSync('./settings.production.json') ? './settings.production.json' : './settings.development.json';
-    return gulp.src(configPath, {allowEmpty: true})
-    .pipe(rename('settings.json'))
-    .pipe(gulp.dest(paths.dist));
-}));
-
-gulp.task("email-templates:dist", function() {
-    return gulp.src(paths.srcPrivate)
-        .pipe(gulp.dest(paths.distPrivate));
-});
-
-gulp.task("compile:dist", function () {
-	return buildTypeScript(paths.dist);
-});
-
-gulp.task("packages:dist", function () {
-    return gulp.src("./package.json")
-        .pipe(gulp.dest(paths.dist));
-});
-
-gulp.task("copy-methods-publications", function() {
-    return gulp.src(['methods.ts', 'publications.ts'])
-        .pipe(gulp.dest(paths.dist));
-});
-
-gulp.task("watch:dist", gulp.series("config:dist", "email-templates:dist", "compile:dist", "packages:dist", "copy-methods-publications", function(done) {
-	gulp.watch(paths.srcTS, gulp.series("compile:dist"));
-	gulp.watch(paths.srcPrivate, gulp.series("email-templates:dist"));
-	gulp.watch(['methods.ts', 'publications.ts'], gulp.series("copy-methods-publications"));
-	done();
-}));
-
-gulp.task("generate-methods-publications", function(done) {
-    exec('python3 methodAndPublicationListGenerator.py', function (err, stdout, stderr) {
-        if (err) {
-            console.error(`exec error: ${err}`);
-            return done(err);
-        }
-        console.log(`stdout: ${stdout}`);
-        console.error(`stderr: ${stderr}`);
-        done();
-    });
-});
-
-gulp.task("build-prod", gulp.series("eslint", "config", "email-templates:dist", "compile:dist", "packages:dist", "generate-methods-publications", "copy-methods-publications", function () {
-    return gulp.src(paths.dist + "/**/*", {dot : true});
-}));