@mongoosejs/studio 0.5.13 → 0.6.0

package/backend/actions/Model/updateDocuments.js

@@ -2,6 +2,7 @@
 
 const Archetype = require('archetype');
 const authorize = require('../../authorize');
+const operationOptions = require('../../helpers/operationOptions');
 
 const UpdateDocumentsParams = new Archetype({
   model: {
@@ -18,10 +19,13 @@ const UpdateDocumentsParams = new Archetype({
   },
   roles: {
     $type: ['string']
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('UpdateDocumentsParams');
 
-module.exports = ({ db }) => async function updateDocuments(params) {
+module.exports = ({ db, options }) => async function updateDocuments(params) {
   const { model, _id, update, roles } = new UpdateDocumentsParams(params);
 
   await authorize('Model.updateDocuments', roles);
@@ -60,7 +64,11 @@ module.exports = ({ db }) => async function updateDocuments(params) {
   }
 
   const result = await Model.
-    updateMany({ _id: { $in: _id } }, updateOperation, { overwriteImmutable: true, runValidators: false });
+    updateMany({ _id: { $in: _id } }, updateOperation, { overwriteImmutable: true, runValidators: false }).
+    setOptions(operationOptions(options, params));
 
   return { result };
 };
+
+module.exports.paramsType = UpdateDocumentsParams;
+module.exports.tags = [];

package/backend/actions/Model/validateDocument.js

@@ -2,6 +2,7 @@
 
 const Archetype = require('archetype');
 const authorize = require('../../authorize');
+const readOperationOptions = require('../../helpers/readOperationOptions');
 const validateDocumentWithTimeout = require('../../helpers/validateDocumentWithTimeout');
 
 const ValidateDocumentParams = new Archetype({
@@ -15,10 +16,17 @@ const ValidateDocumentParams = new Archetype({
   },
   roles: {
     $type: ['string']
+  },
+  maxTimeMS: {
+    $type: 'number'
+  },
+  readPreference: {
+    $type: 'string',
+    $enum: ['secondary', 'secondaryPreferred', 'primary']
   }
 }).compile('ValidateDocumentParams');
 
-module.exports = ({ db }) => async function validateDocument(params) {
+module.exports = ({ db, options }) => async function validateDocument(params) {
   const { model, documentId, roles } = new ValidateDocumentParams(params);
 
   await authorize('Model.validateDocument', roles);
@@ -28,8 +36,13 @@ module.exports = ({ db }) => async function validateDocument(params) {
     throw new Error(`Model ${model} not found`);
   }
 
-  const doc = await Model.findById(documentId).setOptions({ sanitizeFilter: true }).orFail();
+  const doc = await Model.findById(documentId).
+    setOptions(readOperationOptions(options, { sanitizeFilter: true })).
+    orFail();
   return {
     result: await validateDocumentWithTimeout(doc)
   };
 };
+
+module.exports.paramsType = ValidateDocumentParams;
+module.exports.tags = ['readOnly'];

package/backend/actions/Script/createScript.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const Archetype = require('archetype');
+const mongoose = require('mongoose');
+
+const authorize = require('../../authorize');
+
+const CreateScriptParams = new Archetype({
+  initiatedById: {
+    $type: mongoose.Types.ObjectId
+  },
+  script: {
+    $type: 'string',
+    $required: true
+  },
+  roles: {
+    $type: ['string']
+  }
+}).compile('CreateScriptParams');
+
+module.exports = ({ studioConnection, options }) => async function createScript(params) {
+  const { initiatedById, script, roles } = new CreateScriptParams(params);
+
+  await authorize('Script.createScript', roles);
+
+  const Script = studioConnection.model('__Studio_Script');
+  const createdScript = await Script.create({ script, userId: initiatedById });
+  const baseUrl = options?.workspace?.baseUrl?.replace(/\/+$/, '');
+  const url = `${baseUrl ? `${baseUrl}/` : ''}#/script/${createdScript._id}`;
+
+  return { script: createdScript, url };
+};
+
+module.exports.paramsType = CreateScriptParams;
+module.exports.tags = [];
+module.exports.description = 'Create a script for the user to review, edit, dry run, or run in Mongoose Studio. This tool does not execute the script and returns a review URL.';

package/backend/actions/Script/executeScript.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const Archetype = require('archetype');
+const mongoose = require('mongoose');
+
+const authorize = require('../../authorize');
+const readOperationOptions = require('../../helpers/readOperationOptions');
+const createSandbox = require('../../sandbox/createSandbox');
+
+const ExecuteScriptParams = new Archetype({
+  initiatedById: {
+    $type: mongoose.Types.ObjectId
+  },
+  scriptId: {
+    $type: mongoose.Types.ObjectId,
+    $required: true
+  },
+  script: {
+    $type: 'string'
+  },
+  dryRun: {
+    $type: 'boolean',
+    $default: false
+  },
+  roles: {
+    $type: ['string']
+  },
+  maxTimeMS: {
+    $type: 'number'
+  },
+  readPreference: {
+    $type: 'string',
+    $enum: ['secondary', 'secondaryPreferred', 'primary']
+  }
+}).compile('ExecuteScriptParams');
+
+module.exports = ({ db, studioConnection, options }) => async function executeScript(params) {
+  const { initiatedById, scriptId, script, dryRun, roles } = new ExecuteScriptParams(params);
+
+  await authorize('Script.executeScript', roles);
+
+  const Script = studioConnection.model('__Studio_Script');
+  const scriptDoc = await Script.findById(scriptId);
+  if (scriptDoc == null) {
+    throw new Error('Script not found');
+  }
+  if (initiatedById && scriptDoc.userId?.toString() !== initiatedById.toString()) {
+    throw new Error('Unauthorized');
+  }
+
+  let output = null;
+  let error = null;
+
+  if (script != null) {
+    scriptDoc.script = script;
+  }
+  scriptDoc.dryRun = dryRun;
+  scriptDoc.executionStartedAt = new Date();
+  scriptDoc.executionFinishedAt = null;
+  scriptDoc.executionResult = null;
+  await scriptDoc.save();
+
+  const sandbox = createSandbox(db, { ...readOperationOptions(options, params) });
+  try {
+    output = await sandbox.runScript({ script: scriptDoc.script, dryRun });
+  } catch (err) {
+    error = err;
+  } finally {
+    try {
+      await sandbox.close();
+    } catch (_) {
+      // Ignore sandbox cleanup errors so they do not mask the primary result.
+    }
+  }
+
+  scriptDoc.executionFinishedAt = new Date();
+  scriptDoc.executionResult = { output, logs: sandbox.getLogs(), error: error?.message ?? null };
+  await scriptDoc.save();
+
+  if (error != null) {
+    throw new Error(`Script execution failed: ${error.message}`);
+  }
+
+  return { script: scriptDoc };
+};
+
+module.exports.paramsType = ExecuteScriptParams;
+module.exports.tags = [];
+module.exports.mcp = false;

package/backend/actions/Script/getScript.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const Archetype = require('archetype');
+const mongoose = require('mongoose');
+
+const authorize = require('../../authorize');
+const operationOptions = require('../../helpers/operationOptions');
+
+const GetScriptParams = new Archetype({
+  initiatedById: {
+    $type: mongoose.Types.ObjectId
+  },
+  scriptId: {
+    $type: mongoose.Types.ObjectId,
+    $required: true
+  },
+  roles: {
+    $type: ['string']
+  },
+  maxTimeMS: {
+    $type: 'number'
+  }
+}).compile('GetScriptParams');
+
+module.exports = ({ studioConnection, options }) => async function getScript(params) {
+  const { initiatedById, scriptId, roles } = new GetScriptParams(params);
+
+  await authorize('Script.getScript', roles);
+
+  const Script = studioConnection.model('__Studio_Script');
+  const script = await Script.findById(scriptId).setOptions(operationOptions(options, params));
+  if (script == null) {
+    throw new Error('Script not found');
+  }
+  if (initiatedById && script.userId?.toString() !== initiatedById.toString()) {
+    throw new Error('Unauthorized');
+  }
+
+  return { script };
+};
+
+module.exports.paramsType = GetScriptParams;
+module.exports.tags = ['readOnly'];

package/backend/actions/Script/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+exports.createScript = require('./createScript');
+exports.executeScript = require('./executeScript');
+exports.getScript = require('./getScript');

package/backend/actions/Task/cancelTask.js

@@ -2,23 +2,29 @@
 
 const Archetype = require('archetype');
 const mongoose = require('mongoose');
+const operationOptions = require('../../helpers/operationOptions');
 
 const CancelTaskParams = new Archetype({
   taskId: {
     $type: mongoose.Types.ObjectId,
     $required: true
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('CancelTaskParams');
 
-module.exports = ({ db }) => async function cancelTask(params) {
+module.exports = ({ db, options }) => async function cancelTask(params) {
   params = new CancelTaskParams(params);
   const { taskId } = params;
   const { Task } = db.models;
 
-  const task = await Task.findOne({ _id: taskId }).orFail();
+  const task = await Task.findOne({ _id: taskId }).
+    setOptions(operationOptions(options, params)).
+    orFail();
 
   const cancelledTask = await Task.cancelTask({ _id: taskId });
   return {
     task: cancelledTask
   };
-};
+};

package/backend/actions/Task/getTaskOverview.js

@@ -2,12 +2,16 @@
 
 const Archetype = require('archetype');
 const escape = require('regexp.escape');
+const operationOptions = require('../../helpers/operationOptions');
 
 const GetTaskOverviewParams = new Archetype({
   start: { $type: Date },
   end: { $type: Date },
   status: { $type: 'string' },
-  name: { $type: 'string' }
+  name: { $type: 'string' },
+  maxTimeMS: {
+    $type: 'number'
+  }
 }).compile('GetTaskOverviewParams');
 
 /** Statuses shown on the Task overview page. */
@@ -34,7 +38,7 @@ function buildMatch(params) {
   return match;
 }
 
-module.exports = ({ db }) => async function getTaskOverview(params) {
+module.exports = ({ db, options }) => async function getTaskOverview(params) {
   params = new GetTaskOverviewParams(params);
   if (typeof params.status === 'string') params.status = params.status.trim();
   if (typeof params.name === 'string') params.name = params.name.trim();
@@ -93,7 +97,7 @@ module.exports = ({ db }) => async function getTaskOverview(params) {
     }
   ];
 
-  const [result] = await Task.aggregate(pipeline);
+  const [result] = await Task.aggregate(pipeline).option(operationOptions(options, params));
 
   return {
     statusCounts: result.statusCounts?.[0] ?? {},

package/backend/actions/Task/getTasks.js

@@ -2,6 +2,7 @@
 
 const Archetype = require('archetype');
 const escape = require('regexp.escape');
+const operationOptions = require('../../helpers/operationOptions');
 
 const GetTasksParams = new Archetype({
   start: { $type: Date },
@@ -9,7 +10,10 @@ const GetTasksParams = new Archetype({
   status: { $type: 'string' },
   name: { $type: 'string' },
   skip: { $type: 'number', $default: 0 },
-  limit: { $type: 'number', $default: 100 }
+  limit: { $type: 'number', $default: 100 },
+  maxTimeMS: {
+    $type: 'number'
+  }
 }).compile('GetTasksParams');
 
 const ALL_STATUSES = ['pending', 'in_progress', 'succeeded', 'failed', 'cancelled', 'unknown'];
@@ -55,7 +59,7 @@ const TASK_PROJECT_STAGE = {
   parameters: '$payload'
 };
 
-module.exports = ({ db }) => async function getTasks(params) {
+module.exports = ({ db, options }) => async function getTasks(params) {
   params = new GetTasksParams(params);
   if (typeof params.status === 'string') params.status = params.status.trim();
   if (typeof params.name === 'string') params.name = params.name.trim();
@@ -96,7 +100,7 @@ module.exports = ({ db }) => async function getTasks(params) {
     }
   ];
 
-  const [result] = await Task.aggregate(pipeline);
+  const [result] = await Task.aggregate(pipeline).option(operationOptions(options, params));
   const tasks = result.tasks || [];
   const numDocs = (result.count && result.count[0] && result.count[0].total) || 0;
   const statusCounts = result.statusCounts?.[0] ?? {};

package/backend/actions/Task/getTasksOverTime.js

@@ -1,16 +1,20 @@
 'use strict';
 
 const Archetype = require('archetype');
+const operationOptions = require('../../helpers/operationOptions');
 
 const GetTasksOverTimeParams = new Archetype({
   start: { $type: Date },
   end: { $type: Date },
-  bucketSizeMs: { $type: 'number' }
+  bucketSizeMs: { $type: 'number' },
+  maxTimeMS: {
+    $type: 'number'
+  }
 }).compile('GetTasksOverTimeParams');
 
 const TRACKED_STATUSES = ['succeeded', 'failed', 'cancelled'];
 
-module.exports = ({ db }) => async function getTasksOverTime(params) {
+module.exports = ({ db, options }) => async function getTasksOverTime(params) {
   params = new GetTasksOverTimeParams(params);
   const { Task } = db.models;
   const { start, end, bucketSizeMs } = params;
@@ -54,7 +58,7 @@ module.exports = ({ db }) => async function getTasksOverTime(params) {
     { $sort: { _id: 1 } }
   ];
 
-  const results = await Task.aggregate(pipeline);
+  const results = await Task.aggregate(pipeline).option(operationOptions(options, params));
 
   return results.map(r => {
     const bucket = { timestamp: r._id, succeeded: 0, failed: 0, cancelled: 0 };

package/backend/actions/Task/rescheduleTask.js

@@ -2,6 +2,7 @@
 
 const Archetype = require('archetype');
 const mongoose = require('mongoose');
+const operationOptions = require('../../helpers/operationOptions');
 
 const RescheduleTaskParams = new Archetype({
   taskId: {
@@ -11,15 +12,20 @@ const RescheduleTaskParams = new Archetype({
   scheduledAt: {
     $type: Date,
     $required: true
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('RescheduleTaskParams');
 
-module.exports = ({ db }) => async function rescheduleTask(params) {
+module.exports = ({ db, options }) => async function rescheduleTask(params) {
   params = new RescheduleTaskParams(params);
   const { taskId, scheduledAt } = params;
   const { Task } = db.models;
 
-  const task = await Task.findOne({ _id: taskId }).orFail();
+  const task = await Task.findOne({ _id: taskId }).
+    setOptions(operationOptions(options, params)).
+    orFail();
 
   if (scheduledAt < Date.now()) {
     throw new Error('Cannot reschedule a task for the past');
@@ -36,4 +42,4 @@ module.exports = ({ db }) => async function rescheduleTask(params) {
   return {
     task
   };
-};
+};

package/backend/actions/Task/runTask.js

@@ -2,24 +2,30 @@
 
 const Archetype = require('archetype');
 const mongoose = require('mongoose');
+const operationOptions = require('../../helpers/operationOptions');
 
 const RunTaskParams = new Archetype({
   taskId: {
     $type: mongoose.Types.ObjectId,
     $required: true
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('RunTaskParams');
 
-module.exports = ({ db }) => async function runTask(params) {
+module.exports = ({ db, options }) => async function runTask(params) {
   params = new RunTaskParams(params);
   const { taskId } = params;
   const { Task } = db.models;
 
-  const task = await Task.findOne({ _id: taskId }).orFail();
+  const task = await Task.findOne({ _id: taskId }).
+    setOptions(operationOptions(options, params)).
+    orFail();
 
   const executedTask = await Task.execute(task);
  
   return {
     task: executedTask
   };
-};
+};

package/backend/actions/index.js

@@ -5,5 +5,6 @@ exports.ChatThread = require('./ChatThread');
 exports.Dashboard = require('./Dashboard');
 exports.getCapabilities = require('./getCapabilities');
 exports.Model = require('./Model');
+exports.Script = require('./Script');
 exports.status = require('./status');
 exports.Task = require('./Task');

package/backend/authorize.js

@@ -14,6 +14,7 @@ const actionsToRequiredRoles = {
   'Dashboard.getDashboards': ['owner', 'admin', 'member', 'readonly', 'dashboards'],
   'Dashboard.updateDashboard': ['owner', 'admin', 'member'],
   'Model.createDocument': ['owner', 'admin', 'member'],
+  'Model.createChatMessage': ['owner', 'admin', 'member'],
   'Model.analyzeSchema': ['owner', 'admin', 'member', 'readonly'],
   'Model.updateDocument': ['owner', 'admin', 'member'],
   'Model.validateDocument': ['owner', 'admin', 'member', 'readonly'],
@@ -24,6 +25,7 @@ const actionsToRequiredRoles = {
   'Model.executeDocumentScript': ['owner', 'admin', 'member'],
   'Model.exportQueryResults': ['owner', 'admin', 'member', 'readonly'],
   'Model.getDocument': ['owner', 'admin', 'member', 'readonly'],
+  'Model.getCollectionInfo': ['owner', 'admin', 'member', 'readonly'],
   'Model.getDocuments': ['owner', 'admin', 'member', 'readonly'],
   'Model.getDocumentsStream': ['owner', 'admin', 'member', 'readonly'],
   'Model.getSuggestedProjection': ['owner', 'admin', 'member', 'readonly'],
@@ -32,7 +34,10 @@ const actionsToRequiredRoles = {
   'Model.listModels': ['owner', 'admin', 'member', 'readonly'],
   'Model.streamDocumentChanges': ['owner', 'admin', 'member', 'readonly'],
   'Model.streamChatMessage': ['owner', 'admin', 'member', 'readonly'],
-  'Model.updateDocuments': ['owner', 'admin', 'member']
+  'Model.updateDocuments': ['owner', 'admin', 'member'],
+  'Script.createScript': ['owner', 'admin', 'member', 'readonly'],
+  'Script.executeScript': ['owner', 'admin', 'member', 'readonly'],
+  'Script.getScript': ['owner', 'admin', 'member', 'readonly']
 };
 
 module.exports = function authorize(action, roles) {

package/backend/db/scriptSchema.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const mongoose = require('mongoose');
+
+const scriptSchema = new mongoose.Schema({
+  script: {
+    type: String,
+    required: true
+  },
+  executionResult: new mongoose.Schema({
+    output: mongoose.Schema.Types.Mixed,
+    logs: String,
+    error: String
+  }, { _id: false }),
+  userId: {
+    type: mongoose.Schema.Types.ObjectId
+  },
+  dryRun: {
+    type: Boolean
+  },
+  executionStartedAt: {
+    type: Date
+  },
+  executionFinishedAt: {
+    type: Date
+  }
+}, { timestamps: true });
+
+module.exports = scriptSchema;

package/backend/helpers/omitNullish.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = function omitNullish(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value != null));
+};

package/backend/helpers/operationOptions.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const omitNullish = require('./omitNullish');
+
+/**
+ * Options to apply to a MongoDB operation: the configured query time limit,
+ * narrowed by any limit the request itself carries.
+ *
+ * Per-request limits arrive as params, which trusted middleware sets from the
+ * caller's authorization: an MCP OAuth grant, for example, caps every operation
+ * the AI client runs. They are intersected with the host application's
+ * configuration rather than replacing it, so a request can only ever ask for
+ * less than the host allows, never more.
+ */
+module.exports = function operationOptions(options, params, extra) {
+  return omitNullish({ ...extra, maxTimeMS: resolveMaxTimeMS(options, params) });
+};
+
+module.exports.resolveMaxTimeMS = resolveMaxTimeMS;
+
+function resolveMaxTimeMS(options, params) {
+  const requested = Number(params?.maxTimeMS);
+  const limits = [options?.maxTimeMS, Number.isFinite(requested) && requested > 0 ? requested : null].
+    filter(limit => limit != null);
+  return limits.length === 0 ? null : Math.min(...limits);
+}

package/backend/helpers/readOperationOptions.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const operationOptions = require('./operationOptions');
+
+const readPreferenceRank = {
+  secondary: 0,
+  secondaryPreferred: 1,
+  primary: 2
+};
+
+/**
+ * Options to apply to a read against the application database: everything
+ * `operationOptions()` resolves, plus the read preference. MCP OAuth grants use
+ * the read preference to keep AI clients off the primary, so like the query time
+ * limit it is resolved to whichever of the configured and requested values is
+ * more restrictive.
+ */
+module.exports = function readOperationOptions(options, params, extra) {
+  return operationOptions(options, params, {
+    ...extra,
+    readPreference: resolveReadPreference(options, params)
+  });
+};
+
+function resolveReadPreference(options, params) {
+  const preferences = [options?.readPreference, params?.readPreference].
+    filter(preference => readPreferenceRank[preference] != null);
+  return preferences.length === 0 ?
+    null :
+    preferences.reduce((result, preference) => readPreferenceRank[preference] < readPreferenceRank[result] ? preference : result);
+}

package/backend/index.js

@@ -8,6 +8,7 @@ const chatMessageSchema = require('./db/chatMessageSchema');
 const chatThreadSchema = require('./db/chatThreadSchema');
 const dashboardSchema = require('./db/dashboardSchema');
 const dashboardResultSchema = require('./db/dashboardResultSchema');
+const scriptSchema = require('./db/scriptSchema');
 
 module.exports = function backend(db, studioConnection, options) {
   db = db || mongoose.connection;
@@ -16,10 +17,11 @@ module.exports = function backend(db, studioConnection, options) {
   }
 
   studioConnection = studioConnection ?? db;
-  const Dashboard = studioConnection.model('__Studio_Dashboard', dashboardSchema, 'studio__dashboards');
-  const DashboardResult = studioConnection.model('__Studio_DashboardResult', dashboardResultSchema, 'studio__dashboardResults');
-  const ChatMessage = studioConnection.model('__Studio_ChatMessage', chatMessageSchema, 'studio__chatMessages');
-  const ChatThread = studioConnection.model('__Studio_ChatThread', chatThreadSchema, 'studio__chatThreads');
+  studioConnection.model('__Studio_Dashboard', dashboardSchema, 'studio__dashboards');
+  studioConnection.model('__Studio_DashboardResult', dashboardResultSchema, 'studio__dashboardResults');
+  studioConnection.model('__Studio_ChatMessage', chatMessageSchema, 'studio__chatMessages');
+  studioConnection.model('__Studio_ChatThread', chatThreadSchema, 'studio__chatThreads');
+  studioConnection.model('__Studio_Script', scriptSchema, 'studio__scripts');
 
   let changeStream = null;
   if (options?.changeStream) {

package/backend/integrations/mothership.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { defaultMothershipURL } = require('../../constants');
+
+async function post(path, params, options) {
+  const mothershipUrl = options?._mothershipUrl || defaultMothershipURL;
+  const mcpOAuthUrl = `${new URL(mothershipUrl).origin}/mcp-oauth`;
+  const response = await fetch(`${mcpOAuthUrl}/${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params)
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const error = new Error(data?.message || `Mothership request failed with status ${response.status}`);
+    error.status = response.status;
+    throw error;
+  }
+  return data;
+}
+
+exports.MCPOAuthToken = {
+  introspectMCPAccessToken: (params, options) => post('MCPOAuthToken/introspectMCPAccessToken', params, options)
+};
+
+exports.Workspace = {
+  registerMCPResource: (params, options) => post('Workspace/registerMCPResource', params, options)
+};