@modelprofile.com/flexharness 4.1.0 → 4.1.2

package/ts/utils.validation.ts

@@ -0,0 +1,204 @@
+import { FlexHarnessValidationError } from './errors.js';
+import { FLEX_PROJECT_MANAGEMENT_LIMITS } from './interfaces.js';
+import type {
+  IFlexCreateProjectTaskInput,
+  IFlexErrorInfo,
+  IFlexPromptOptions,
+  IFlexSlashCommandExecutionOptions,
+  IFlexUpdateProjectTaskInput,
+  IFlexUpdateSessionOptions,
+  TFlexProjectTaskPriority,
+  TFlexProjectTaskStatus,
+} from './interfaces.js';
+
+const maxProjectedErrorNameBytes = 128;
+const maxProjectedErrorMessageBytes = 2048;
+const maxProjectedErrorCodeBytes = 128;
+
+export function validateIdentifier(value: string, name: string): void {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
+  }
+}
+
+export function validateUtf8String(
+  value: unknown,
+  name: string,
+  maxBytes: number,
+  nonEmpty = false,
+): asserts value is string {
+  if (
+    typeof value !== 'string'
+    || (nonEmpty && !value.trim())
+    || Buffer.byteLength(value, 'utf8') > maxBytes
+  ) {
+    throw new FlexHarnessValidationError(
+      `${name} must be ${nonEmpty ? 'a non-empty ' : 'a '}string of at most ${maxBytes} UTF-8 bytes.`,
+    );
+  }
+}
+
+export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError('External error projection is invalid.');
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const unsupportedKey = Reflect.ownKeys(descriptors).find(
+    (key) => typeof key !== 'string' || !['name', 'message', 'code'].includes(key),
+  );
+  const name = descriptors.name?.value;
+  const message = descriptors.message?.value;
+  const code = descriptors.code?.value;
+  if (
+    unsupportedKey
+    || descriptors.name?.get !== undefined
+    || descriptors.name?.set !== undefined
+    || descriptors.message?.get !== undefined
+    || descriptors.message?.set !== undefined
+    || descriptors.code?.get !== undefined
+    || descriptors.code?.set !== undefined
+    || typeof name !== 'string'
+    || !name
+    || Buffer.byteLength(name, 'utf8') > maxProjectedErrorNameBytes
+    || typeof message !== 'string'
+    || !message
+    || Buffer.byteLength(message, 'utf8') > maxProjectedErrorMessageBytes
+    || (code !== undefined
+      && (typeof code !== 'string'
+        || !code
+        || Buffer.byteLength(code, 'utf8') > maxProjectedErrorCodeBytes))
+  ) {
+    throw new FlexHarnessValidationError('External error projection is invalid.');
+  }
+  return Object.freeze({ name, message, ...(code === undefined ? {} : { code }) });
+}
+
+export function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new FlexHarnessValidationError('updateSession options must be a plain object.');
+  }
+  const keys = Object.keys(options);
+  if (keys.length === 0) throw new FlexHarnessValidationError('updateSession requires title or archived.');
+  const unsupportedKey = keys.find((key) => key !== 'title' && key !== 'archived');
+  if (unsupportedKey) throw new FlexHarnessValidationError(`updateSession does not support "${unsupportedKey}".`);
+  if (Object.prototype.hasOwnProperty.call(options, 'title') && options.title !== null) {
+    validateUtf8String(
+      options.title,
+      'title',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes,
+      true,
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'archived') && typeof options.archived !== 'boolean') {
+    throw new FlexHarnessValidationError('archived must be a boolean.');
+  }
+}
+
+export function validateProjectTaskStatus(value: unknown): asserts value is TFlexProjectTaskStatus {
+  if (!['pending', 'in_progress', 'completed', 'cancelled'].includes(String(value))) {
+    throw new FlexHarnessValidationError('Project task status is invalid.');
+  }
+}
+
+export function validateProjectTaskPriority(value: unknown): asserts value is TFlexProjectTaskPriority {
+  if (!['high', 'medium', 'low'].includes(String(value))) {
+    throw new FlexHarnessValidationError('Project task priority is invalid.');
+  }
+}
+
+export function validateProjectTaskId(value: unknown): asserts value is string {
+  validateUtf8String(
+    value,
+    'project task id',
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes,
+    true,
+  );
+}
+
+export function validateProjectTaskContent(value: unknown): asserts value is string {
+  validateUtf8String(
+    value,
+    'project task content',
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes,
+    true,
+  );
+}
+
+export function validateCreateProjectTaskInput(input: IFlexCreateProjectTaskInput): void {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new FlexHarnessValidationError('Project task create input must be a plain object.');
+  }
+  const unsupported = Object.keys(input)
+    .find((key) => !['id', 'content', 'status', 'priority'].includes(key));
+  if (unsupported) {
+    throw new FlexHarnessValidationError(`Project task create input does not support "${unsupported}".`);
+  }
+  validateProjectTaskId(input.id);
+  validateProjectTaskContent(input.content);
+  if (input.status !== undefined) validateProjectTaskStatus(input.status);
+  if (input.priority !== undefined) validateProjectTaskPriority(input.priority);
+}
+
+export function validateUpdateProjectTaskInput(input: IFlexUpdateProjectTaskInput): void {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new FlexHarnessValidationError('Project task update input must be a plain object.');
+  }
+  const keys = Object.keys(input);
+  const unsupported = keys.find((key) => !['id', 'content', 'status', 'priority'].includes(key));
+  if (unsupported) {
+    throw new FlexHarnessValidationError(`Project task update input does not support "${unsupported}".`);
+  }
+  if (!keys.some((key) => key !== 'id')) {
+    throw new FlexHarnessValidationError('Project task update requires a changed field.');
+  }
+  validateProjectTaskId(input.id);
+  if (input.content !== undefined) validateProjectTaskContent(input.content);
+  if (input.status !== undefined) validateProjectTaskStatus(input.status);
+  if (input.priority !== undefined) validateProjectTaskPriority(input.priority);
+}
+
+export function validatePromptOptions(options: IFlexPromptOptions, scheduled: boolean): void {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new FlexHarnessValidationError('Prompt options must be a plain object.');
+  }
+  const supported = scheduled
+    ? ['modelHint', 'system', 'maxSteps', 'debounceMs']
+    : ['modelHint', 'system', 'maxSteps'];
+  const unsupported = Object.keys(options).find((key) => !supported.includes(key));
+  if (unsupported) throw new FlexHarnessValidationError(`Prompt options do not support "${unsupported}".`);
+  if (options.modelHint !== undefined) validateIdentifier(options.modelHint, 'modelHint');
+  if (options.system !== undefined) validateIdentifier(options.system, 'system');
+  if (options.maxSteps !== undefined && (!Number.isSafeInteger(options.maxSteps) || options.maxSteps < 1)) {
+    throw new FlexHarnessValidationError('maxSteps must be a positive integer.');
+  }
+}
+
+export function validateSlashCommandExecutionOptions(
+  options: IFlexSlashCommandExecutionOptions,
+): IFlexPromptOptions {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new FlexHarnessValidationError('Slash command execution options must be a plain object.');
+  }
+  const unsupported = Object.keys(options)
+    .find((key) => !['modelHint', 'system', 'maxSteps', 'signal'].includes(key));
+  if (unsupported) {
+    throw new FlexHarnessValidationError(
+      `Slash command execution options do not support "${unsupported}".`,
+    );
+  }
+  if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+    throw new FlexHarnessValidationError('Slash command signal must be an AbortSignal.');
+  }
+  const promptOptions: IFlexPromptOptions = {
+    ...(options.modelHint === undefined ? {} : { modelHint: options.modelHint }),
+    ...(options.system === undefined ? {} : { system: options.system }),
+    ...(options.maxSteps === undefined ? {} : { maxSteps: options.maxSteps }),
+  };
+  validatePromptOptions(promptOptions, false);
+  return promptOptions;
+}