@resolveio/server-lib 22.2.33 → 22.2.34

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

@@ -0,0 +1,115 @@
+# 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

@@ -0,0 +1,7 @@
+// 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

@@ -0,0 +1,44 @@
+// 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

@@ -0,0 +1,103 @@
+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

@@ -0,0 +1,216 @@
+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});
+}));