@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/work-item-validation.js

@@ -1,3 +1,29 @@
+const apiValidation = require('./api-validation');
+
+const WORK_ITEM_SCOPES = Object.freeze(['fan-out']);
+const WORK_ITEM_FEEDBACK_RATINGS = Object.freeze(['up', 'down']);
+const PR_FOLLOWUP_FIELDS = Object.freeze([
+  'parent_pr_url',
+  'parent_pr_id',
+  'parent_comment_id',
+  'parent_comment_author',
+]);
+const PR_FOLLOWUP_MAX_FIELD_LEN = 512;
+const PR_REFERENCE_FIELDS = Object.freeze([
+  'targetPr',
+  'pr',
+  'pr_id',
+  'prId',
+  'sourcePr',
+  'pullRequest',
+  'prUrl',
+]);
+const META_BOOLEAN_FIELDS = Object.freeze([
+  'keep_processes',
+  'keep_processes_skip_workdir_check',
+  'managed_spawn',
+]);
+
 function _hasText(value) {
   return typeof value === 'string' && value.trim().length > 0;
 }
@@ -44,9 +70,544 @@ function isMalformedPhantomWorkItem(item) {
     && !hasWorkItemProvenance(item);
 }
 
+function _hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function _inputError(message, options = {}) {
+  throw new apiValidation.ApiInputError(message, {
+    code: options.code || 'invalid-work-item-input',
+    statusCode: options.statusCode,
+    field: options.field,
+    path: options.path || options.field,
+    expected: options.expected,
+    rejectedValue: options.rejectedValue,
+    allowedValues: options.allowedValues,
+  });
+}
+
+function _validateBody(body) {
+  return apiValidation.validatePlainObject(body, {
+    field: 'body',
+    path: 'body',
+    message: 'work-item request body must be a plain object',
+  });
+}
+
+function _normalizeIdentifier(value, field, options = {}) {
+  if (value === undefined && options.optional) return undefined;
+  return apiValidation.validateIdentifier(value, {
+    field,
+    path: field,
+    trim: true,
+    maxLength: options.maxLength || 128,
+    code: options.code,
+    message: `${field} must be a valid identifier`,
+  });
+}
+
+function _normalizeSource(value, field = 'source', options = {}) {
+  if (value === undefined && options.optional) return undefined;
+  if (value === null && options.nullable) return '';
+  return apiValidation.validateString(value, {
+    field,
+    path: field,
+    trim: true,
+    allowEmpty: options.allowEmpty !== false,
+    message: `${field} must be a string`,
+  });
+}
+
+function _normalizeText(value, field, options = {}) {
+  if (value === undefined && options.optional) return undefined;
+  if (value === null && options.nullable) return null;
+  return apiValidation.validateString(value, {
+    field,
+    path: field,
+    trim: options.trim === true,
+    allowEmpty: options.allowEmpty !== false,
+    maxLength: options.maxLength,
+    message: `${field} must be ${options.allowEmpty === false ? 'a non-empty string' : 'a string'}`,
+  });
+}
+
+function _normalizeBoolean(value, field) {
+  return apiValidation.validateBoolean(value, {
+    field,
+    path: field,
+    message: `${field} must be a boolean`,
+  });
+}
+
+function _normalizePriority(value, validatePriority) {
+  if (typeof validatePriority !== 'function') {
+    throw new TypeError('normalize work-item input requires validatePriority');
+  }
+  const error = validatePriority(value);
+  if (!error) return value;
+  _inputError(error.error, {
+    code: error.code,
+    field: 'priority',
+    expected: 'canonical work-item priority',
+    rejectedValue: error.rejectedValue,
+    allowedValues: error.allowedValues,
+  });
+}
+
+function _normalizeWorkType(value, options = {}) {
+  if (value === undefined) return options.defaultValue;
+  const raw = _normalizeText(value, 'type', {
+    trim: true,
+    allowEmpty: false,
+    maxLength: 64,
+  });
+  const normalized = typeof options.normalizeWorkType === 'function'
+    ? options.normalizeWorkType(raw)
+    : raw;
+  const allowed = options.allowedWorkTypes instanceof Set
+    ? [...options.allowedWorkTypes]
+    : (Array.isArray(options.allowedWorkTypes) ? options.allowedWorkTypes : []);
+  if (!allowed.includes(normalized)) {
+    _inputError('type must be a recognized work-item type', {
+      code: 'invalid-work-item-type',
+      field: 'type',
+      rejectedValue: value,
+      allowedValues: allowed,
+    });
+  }
+  return normalized;
+}
+
+function _normalizeAgent(value, field, options = {}) {
+  if (value === undefined && options.optional) return undefined;
+  if (value === null && options.nullable) return null;
+  const agent = _normalizeText(value, field, {
+    trim: true,
+    allowEmpty: options.allowEmpty === true,
+    maxLength: 128,
+  });
+  if (!agent && options.allowEmpty) return null;
+  _normalizeIdentifier(agent, field, { code: 'invalid-agent' });
+  const knownAgents = Array.isArray(options.knownAgents) ? options.knownAgents : [];
+  const tempAllowed = options.allowTempAgents === true && /^temp-/.test(agent);
+  if (knownAgents.length > 0 && !knownAgents.includes(agent) && !tempAllowed) {
+    _inputError(`Unknown agent "${agent}". Valid agents: ${knownAgents.join(', ')}`, {
+      code: 'unknown-agent',
+      field,
+      rejectedValue: value,
+      allowedValues: knownAgents,
+    });
+  }
+  return agent;
+}
+
+function _normalizeAgents(value, options = {}) {
+  if (value === undefined) return undefined;
+  const entries = typeof value === 'string'
+    ? [value]
+    : apiValidation.validateArray(value, {
+      field: 'agents',
+      path: 'agents',
+      message: 'agents must be a string or an array of strings',
+    });
+  const normalized = [];
+  entries.forEach((entry, index) => {
+    if (typeof entry !== 'string') {
+      _inputError('agents entries must be strings', {
+        field: 'agents',
+        path: ['agents', index],
+        rejectedValue: entry,
+      });
+    }
+    if (!entry.trim()) return;
+    normalized.push(_normalizeAgent(entry, 'agents', options));
+  });
+  return normalized;
+}
+
+function _normalizeStringList(value, field, options = {}) {
+  if (value === undefined) return undefined;
+  const entries = options.allowStringAlias && typeof value === 'string'
+    ? value.split(/\r?\n/)
+    : apiValidation.validateArray(value, {
+      field,
+      path: field,
+      message: options.allowStringAlias
+        ? `${field} must be a string or an array of strings`
+        : `${field} must be an array of strings`,
+    });
+  const normalized = [];
+  entries.forEach((entry, index) => {
+    if (typeof entry !== 'string') {
+      _inputError(`${field} entries must be strings`, {
+        field,
+        path: [field, index],
+        rejectedValue: entry,
+      });
+    }
+    const trimmed = entry.trim();
+    if (!trimmed) return;
+    if (options.identifiers) _normalizeIdentifier(trimmed, field);
+    normalized.push(trimmed);
+  });
+  return normalized;
+}
+
+function _normalizeReferences(value) {
+  if (value === undefined) return undefined;
+  const references = apiValidation.validateArray(value, {
+    field: 'references',
+    path: 'references',
+    message: 'references must be an array of objects',
+  });
+  return references.map((entry, index) => {
+    apiValidation.validatePlainObject(entry, {
+      field: 'references',
+      path: ['references', index],
+      message: 'references entries must be plain objects',
+    });
+    const url = _normalizeText(entry.url, 'references', {
+      trim: true,
+      allowEmpty: false,
+    });
+    const normalized = { ...entry, url };
+    for (const field of ['title', 'label', 'type', 'description']) {
+      if (_hasOwn(entry, field)) {
+        normalized[field] = _normalizeText(entry[field], 'references', {
+          trim: true,
+        });
+      }
+    }
+    return normalized;
+  });
+}
+
+function _normalizePrFollowup(value) {
+  if (value === undefined || value === null) return null;
+  apiValidation.validatePlainObject(value, {
+    field: 'meta.pr_followup',
+    path: 'meta.pr_followup',
+    message: 'meta.pr_followup must be a plain object',
+  });
+  const normalized = {};
+  for (const field of PR_FOLLOWUP_FIELDS) {
+    normalized[field] = _normalizeText(value[field], `meta.pr_followup.${field}`, {
+      trim: true,
+      allowEmpty: false,
+      maxLength: PR_FOLLOWUP_MAX_FIELD_LEN,
+    });
+  }
+  return normalized;
+}
+
+function validatePrFollowupShape(value) {
+  try {
+    return { valid: true, value: _normalizePrFollowup(value) };
+  } catch (error) {
+    return { valid: false, error: error.message };
+  }
+}
+
+function _normalizeWorkdir(value, field, validateWorkdir) {
+  if (typeof validateWorkdir !== 'function') {
+    throw new TypeError('normalize work-item input requires validateWorkdir');
+  }
+  const result = validateWorkdir(value);
+  if (!result || result.valid !== true) {
+    _inputError(`${field}: ${result?.error || 'invalid workdir'}`, {
+      code: 'invalid-workdir',
+      field,
+      rejectedValue: value,
+    });
+  }
+  return result.value;
+}
+
+function _normalizeMeta(value, options = {}) {
+  if (value === undefined) return undefined;
+  apiValidation.validatePlainObject(value, {
+    field: 'meta',
+    path: 'meta',
+    message: 'meta must be a plain object',
+  });
+  const normalized = { ...value };
+  if (_hasOwn(value, 'pr_followup')) {
+    const followup = _normalizePrFollowup(value.pr_followup);
+    if (followup) normalized.pr_followup = followup;
+    else delete normalized.pr_followup;
+  }
+  if (_hasOwn(value, 'workdir')) {
+    const workdir = _normalizeWorkdir(value.workdir, 'meta.workdir', options.validateWorkdir);
+    if (workdir === null) delete normalized.workdir;
+    else normalized.workdir = workdir;
+  }
+  for (const field of META_BOOLEAN_FIELDS) {
+    if (_hasOwn(value, field)) {
+      normalized[field] = _normalizeBoolean(value[field], `meta.${field}`);
+    }
+  }
+  return normalized;
+}
+
+function _normalizePrFields(body, normalized) {
+  for (const field of PR_REFERENCE_FIELDS) {
+    if (!_hasOwn(body, field)) continue;
+    const value = body[field];
+    if ((typeof value !== 'string' || !value.trim())
+        && (!Number.isInteger(value) || value <= 0)) {
+      _inputError(`${field} must be a non-empty string or positive integer`, {
+        field,
+        rejectedValue: value,
+      });
+    }
+    normalized[field] = typeof value === 'string' ? value.trim() : value;
+  }
+  if (_hasOwn(body, 'prNumber')) {
+    const value = body.prNumber;
+    const numeric = typeof value === 'string' && /^\d+$/.test(value.trim())
+      ? Number(value.trim())
+      : value;
+    if (!Number.isSafeInteger(numeric) || numeric <= 0) {
+      _inputError('prNumber must be a positive integer', {
+        field: 'prNumber',
+        rejectedValue: value,
+      });
+    }
+    normalized.prNumber = numeric;
+  }
+  for (const field of ['prBranch', 'prTitle']) {
+    if (_hasOwn(body, field)) {
+      normalized[field] = _normalizeText(body[field], field, {
+        trim: true,
+        allowEmpty: false,
+      });
+    }
+  }
+}
+
+function normalizeCreateInput(body, options = {}) {
+  _validateBody(body);
+  const normalized = { ...body };
+  normalized.title = _normalizeText(body.title, 'title', {
+    trim: true,
+    allowEmpty: false,
+  });
+  normalized.description = body.description === undefined
+    ? ''
+    : _normalizeText(body.description, 'description');
+  normalized.type = _normalizeWorkType(body.type, {
+    defaultValue: options.defaultType,
+    normalizeWorkType: options.normalizeWorkType,
+    allowedWorkTypes: options.allowedWorkTypes,
+  });
+  _normalizePriority(body.priority, options.validatePriority);
+  if (_hasOwn(body, 'project')) {
+    normalized.project = _normalizeSource(body.project, 'project', {
+      nullable: true,
+      allowEmpty: true,
+    });
+  }
+  normalized.agent = _normalizeAgent(body.agent, 'agent', {
+    optional: true,
+    nullable: true,
+    allowEmpty: true,
+    knownAgents: options.knownAgents,
+    allowTempAgents: options.allowTempAgents,
+  });
+  normalized.agents = _normalizeAgents(body.agents, {
+    knownAgents: options.knownAgents,
+    allowTempAgents: options.allowTempAgents,
+  });
+  if (_hasOwn(body, 'scope')) {
+    const scope = _normalizeText(body.scope, 'scope', {
+      trim: true,
+      allowEmpty: false,
+      maxLength: 64,
+    });
+    if (!WORK_ITEM_SCOPES.includes(scope)) {
+      _inputError('scope must be a recognized work-item scope', {
+        field: 'scope',
+        rejectedValue: body.scope,
+        allowedValues: WORK_ITEM_SCOPES,
+      });
+    }
+    normalized.scope = scope;
+  }
+  normalized.references = _normalizeReferences(body.references);
+  normalized.acceptanceCriteria = _normalizeStringList(
+    body.acceptanceCriteria,
+    'acceptanceCriteria',
+    { allowStringAlias: true },
+  );
+  normalized.depends_on = _normalizeStringList(body.depends_on, 'depends_on', {
+    identifiers: true,
+  });
+  for (const field of ['skipPr', 'oneShot', 'agentLock', 'hardAgent']) {
+    if (_hasOwn(body, field)) normalized[field] = _normalizeBoolean(body[field], field);
+  }
+  normalized.meta = _normalizeMeta(body.meta, options);
+  for (const field of ['planFile', 'branch', 'branchStrategy', 'featureBranch']) {
+    if (_hasOwn(body, field)) {
+      normalized[field] = _normalizeText(body[field], field, {
+        trim: true,
+        allowEmpty: false,
+      });
+    }
+  }
+  _normalizePrFields(body, normalized);
+  return normalized;
+}
+
+function normalizeUpdateInput(body, options = {}) {
+  _validateBody(body);
+  const normalized = { ...body };
+  normalized.id = _normalizeIdentifier(body.id, 'id');
+  if (_hasOwn(body, 'source')) {
+    normalized.source = _normalizeSource(body.source, 'source', {
+      nullable: true,
+      allowEmpty: true,
+    });
+  }
+  if (_hasOwn(body, 'title')) {
+    normalized.title = _normalizeText(body.title, 'title', {
+      trim: true,
+      allowEmpty: false,
+    });
+  }
+  if (_hasOwn(body, 'description')) {
+    normalized.description = _normalizeText(body.description, 'description');
+  }
+  if (_hasOwn(body, 'type')) {
+    normalized.type = _normalizeWorkType(body.type, {
+      normalizeWorkType: options.normalizeWorkType,
+      allowedWorkTypes: options.allowedWorkTypes,
+    });
+  }
+  _normalizePriority(body.priority, options.validatePriority);
+  if (_hasOwn(body, 'agent')) {
+    normalized.agent = _normalizeAgent(body.agent, 'agent', {
+      nullable: true,
+      allowEmpty: true,
+      knownAgents: options.knownAgents,
+      allowTempAgents: options.allowTempAgents,
+    });
+  }
+  if (_hasOwn(body, 'project')) {
+    normalized.project = _normalizeSource(body.project, 'project', {
+      nullable: true,
+      allowEmpty: true,
+    });
+  }
+  normalized.references = _normalizeReferences(body.references);
+  normalized.acceptanceCriteria = _normalizeStringList(
+    body.acceptanceCriteria,
+    'acceptanceCriteria',
+    { allowStringAlias: true },
+  );
+  normalized.depends_on = _normalizeStringList(body.depends_on, 'depends_on', {
+    identifiers: true,
+  });
+  if (_hasOwn(body, 'workdir')) {
+    normalized.workdir = _normalizeWorkdir(body.workdir, 'workdir', options.validateWorkdir);
+  }
+  normalized.meta = _normalizeMeta(body.meta, options);
+  return normalized;
+}
+
+function normalizeActionInput(action, body, options = {}) {
+  _validateBody(body);
+  const normalized = {
+    ...body,
+    id: _normalizeIdentifier(body.id, 'id'),
+  };
+  if (_hasOwn(body, 'source')) {
+    normalized.source = _normalizeSource(body.source, 'source', {
+      nullable: true,
+      allowEmpty: true,
+    });
+  }
+  if (action === 'retry') {
+    if (_hasOwn(body, 'prdFile')) {
+      const prdFile = _normalizeText(body.prdFile, 'prdFile', {
+        trim: true,
+        allowEmpty: false,
+      });
+      if (typeof options.validatePrdFilename !== 'function') {
+        throw new TypeError('retry validation requires validatePrdFilename');
+      }
+      try {
+        normalized.prdFile = options.validatePrdFilename(prdFile);
+      } catch (error) {
+        _inputError(error.message, {
+          code: 'invalid-prd-filename',
+          field: 'prdFile',
+          rejectedValue: body.prdFile,
+        });
+      }
+    }
+    if (_hasOwn(body, 'force')) normalized.force = _normalizeBoolean(body.force, 'force');
+  } else if (action === 'cancel') {
+    if (_hasOwn(body, 'reason')) {
+      normalized.reason = _normalizeText(body.reason, 'reason', {
+        trim: true,
+      });
+    }
+  } else if (action === 'reopen') {
+    if (_hasOwn(body, 'project')) {
+      normalized.project = _normalizeSource(body.project, 'project', {
+        nullable: true,
+        allowEmpty: true,
+      });
+    }
+    if (_hasOwn(body, 'description')) {
+      normalized.description = _normalizeText(body.description, 'description');
+    }
+  } else if (action === 'feedback') {
+    normalized.rating = apiValidation.validateEnum(body.rating, {
+      field: 'rating',
+      path: 'rating',
+      values: WORK_ITEM_FEEDBACK_RATINGS,
+      message: 'rating must be "up" or "down"',
+    });
+    if (_hasOwn(body, 'comment')) {
+      normalized.comment = _normalizeText(body.comment, 'comment');
+    }
+  }
+  return normalized;
+}
+
+function normalizeReadInput(id, source) {
+  return {
+    id: _normalizeIdentifier(id, 'id'),
+    source: source === undefined
+      ? undefined
+      : _normalizeSource(source, 'source', { allowEmpty: true }),
+  };
+}
+
+function normalizeTraceHeaders(headers = {}) {
+  const normalized = {};
+  for (const [header, field] of [
+    ['x-minions-agent', 'X-Minions-Agent'],
+    ['x-minions-origin-wi', 'X-Minions-Origin-Wi'],
+  ]) {
+    if (!_hasOwn(headers, header)) continue;
+    normalized[header] = _normalizeIdentifier(headers[header], field);
+  }
+  return normalized;
+}
+
 module.exports = {
   hasWorkItemSemantics,
   hasWorkItemProvenance,
   validateNewWorkItem,
   isMalformedPhantomWorkItem,
+  WORK_ITEM_SCOPES,
+  WORK_ITEM_FEEDBACK_RATINGS,
+  validatePrFollowupShape,
+  normalizeCreateInput,
+  normalizeUpdateInput,
+  normalizeActionInput,
+  normalizeReadInput,
+  normalizeTraceHeaders,
 };

package/engine/work-items-store.js

@@ -193,7 +193,7 @@ function readArchivedWorkItemsForScope(scope) {
   return out;
 }
 
-function archiveWorkItem(scope, id) {
+function archiveWorkItem(scope, id, opts = {}) {
   const { getDb, withTransaction } = require('./db');
   const db = getDb();
   const archived = withTransaction(db, () => {
@@ -201,6 +201,17 @@ function archiveWorkItem(scope, id) {
     if (!row) return null;
     const item = _parseRow(row);
     if (!item) throw new Error(`work item ${id} has invalid SQL data`);
+    const allowedStatuses = opts.allowedStatuses instanceof Set
+      ? opts.allowedStatuses
+      : (Array.isArray(opts.allowedStatuses) ? new Set(opts.allowedStatuses) : null);
+    if (allowedStatuses && !allowedStatuses.has(item.status)) {
+      const error = new Error(
+        `cannot archive item with status: ${item.status || 'unknown'}`,
+      );
+      error.code = 'invalid-work-item-status';
+      error.statusCode = 409;
+      throw error;
+    }
     item._archived = true;
     item.archivedAt = item.archivedAt || new Date().toISOString();
     db.prepare('UPDATE work_items SET archived=1, data=?, updated_at=? WHERE scope=? AND id=?')
@@ -287,6 +298,54 @@ function moveWorkItem(sourceScope, targetScope, id, item) {
   return moved;
 }
 
+function moveWorkItemWithUpdate(sourceScope, targetScope, id, updater) {
+  if (typeof updater !== 'function') throw new TypeError('moveWorkItemWithUpdate requires an updater');
+  const { getDb, withTransaction } = require('./db');
+  const db = getDb();
+  const outcome = withTransaction(db, () => {
+    const source = db.prepare(
+      'SELECT data FROM work_items WHERE scope=? AND id=? AND archived=0',
+    ).get(sourceScope, String(id));
+    if (!source) return { moved: false, reason: 'not-found', item: null };
+    const target = db.prepare(
+      'SELECT 1 FROM work_items WHERE scope=? AND id=?',
+    ).get(targetScope, String(id));
+    if (target) return { moved: false, reason: 'target-exists', item: null };
+
+    const current = _parseRow(source);
+    if (!current) throw new Error(`work item ${id} has invalid SQL data`);
+    const updated = updater(current) || current;
+    require('./work-item-validation').validateNewWorkItem(updated);
+    const result = db.prepare(`
+      UPDATE work_items SET
+        scope=?, status=?, type=?, agent=?, parent_id=?, created_at=?,
+        completed_at=?, data=?, updated_at=?
+      WHERE scope=? AND id=? AND archived=0
+    `).run(
+      targetScope,
+      String(updated.status || 'pending'),
+      updated.type || null,
+      updated.dispatched_to || updated.agent || null,
+      updated.parent_id || null,
+      _toMs(updated.created_at || updated.created),
+      _toMs(updated.completed_at || updated.completedAt),
+      JSON.stringify(updated),
+      Date.now(),
+      sourceScope,
+      String(id),
+    );
+    if (Number(result.changes) === 0) {
+      return { moved: false, reason: 'not-found', item: null };
+    }
+    return { moved: true, reason: null, item: updated };
+  });
+  if (outcome.moved) {
+    try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+    try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+  }
+  return outcome;
+}
+
 module.exports = {
   readWorkItemsForScope,
   readAllWorkItems,
@@ -294,6 +353,7 @@ module.exports = {
   archiveWorkItem,
   replaceArchivedWorkItems,
   moveWorkItem,
+  moveWorkItemWithUpdate,
   applyWorkItemsMutation,
   dropScope,
 };