@modelprofile.com/flexharness 3.8.0 → 4.0.1

package/ts/utils.projectmanagement.ts

@@ -0,0 +1,226 @@
+import {
+  FlexHarnessStoreFormatError,
+} from './errors.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION,
+  FLEX_SESSION_GENERATION_ID_MAX_BYTES,
+} from './interfaces.js';
+import type {
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementTombstone,
+  IFlexProjectTask,
+  TFlexProjectManagementRecord,
+} from './interfaces.js';
+import { assertJsonSerializable } from './utils.json.js';
+
+function requireRecord(value: unknown, path: string): Record<string, unknown> {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a plain object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireOnlyKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  path: string,
+): void {
+  const unsupported = Object.keys(value).find((key) => !keys.includes(key));
+  if (unsupported) {
+    throw new FlexHarnessStoreFormatError(`${path}.${unsupported} is not supported.`);
+  }
+}
+
+function requireBoundedString(
+  value: unknown,
+  path: string,
+  maxBytes: number,
+  nonEmpty = false,
+): asserts value is string {
+  if (
+    typeof value !== 'string'
+    || (nonEmpty && !value.trim())
+    || Buffer.byteLength(value, 'utf8') > maxBytes
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path} must be ${nonEmpty ? 'a non-empty ' : 'a '}string of at most ${maxBytes} UTF-8 bytes.`,
+    );
+  }
+}
+
+function requireTimestamp(value: unknown, path: string): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new FlexHarnessStoreFormatError(`${path} must be a canonical ISO timestamp.`);
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== value) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a canonical ISO timestamp.`);
+  }
+}
+
+function requireSessionGeneration(value: Record<string, unknown>, path: string): void {
+  requireBoundedString(
+    value.sessionGenerationId,
+    `${path}.sessionGenerationId`,
+    FLEX_SESSION_GENERATION_ID_MAX_BYTES,
+    true,
+  );
+  if (
+    !Number.isSafeInteger(value.sessionGenerationSequence)
+    || Number(value.sessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.sessionGenerationSequence must be a positive integer.`,
+    );
+  }
+}
+
+function validateTask(value: unknown, path: string): IFlexProjectTask {
+  const task = requireRecord(value, path);
+  requireOnlyKeys(
+    task,
+    ['id', 'content', 'status', 'priority', 'createdAt', 'updatedAt'],
+    path,
+  );
+  requireBoundedString(task.id, `${path}.id`, FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes, true);
+  requireBoundedString(
+    task.content,
+    `${path}.content`,
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes,
+    true,
+  );
+  if (!['pending', 'in_progress', 'completed', 'cancelled'].includes(String(task.status))) {
+    throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+  }
+  if (!['high', 'medium', 'low'].includes(String(task.priority))) {
+    throw new FlexHarnessStoreFormatError(`${path}.priority is invalid.`);
+  }
+  requireTimestamp(task.createdAt, `${path}.createdAt`);
+  requireTimestamp(task.updatedAt, `${path}.updatedAt`);
+  if (task.updatedAt < task.createdAt) {
+    throw new FlexHarnessStoreFormatError(`${path}.updatedAt cannot precede createdAt.`);
+  }
+  return task as unknown as IFlexProjectTask;
+}
+
+export function createEmptyFlexProjectManagementSnapshot(
+  sessionGenerationId: string,
+  sessionGenerationSequence: number,
+): IFlexProjectManagementSnapshot {
+  const snapshot: IFlexProjectManagementSnapshot = {
+    schemaVersion: FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION,
+    revision: 0,
+    sessionGenerationId,
+    sessionGenerationSequence,
+    scratchpad: '',
+    tasks: [],
+  };
+  assertFlexProjectManagementSnapshot(snapshot);
+  return snapshot;
+}
+
+export function assertFlexProjectManagementSnapshot(
+  value: unknown,
+): asserts value is IFlexProjectManagementSnapshot {
+  assertJsonSerializable(value, '$snapshot');
+  const snapshot = requireRecord(value, '$snapshot');
+  requireOnlyKeys(
+    snapshot,
+    [
+      'schemaVersion',
+      'revision',
+      'sessionGenerationId',
+      'sessionGenerationSequence',
+      'goal',
+      'scratchpad',
+      'tasks',
+    ],
+    '$snapshot',
+  );
+  if (snapshot.schemaVersion !== FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION) {
+    throw new FlexHarnessStoreFormatError(
+      `Project management snapshot schemaVersion must be ${FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION}.`,
+    );
+  }
+  if (!Number.isSafeInteger(snapshot.revision) || Number(snapshot.revision) < 0) {
+    throw new FlexHarnessStoreFormatError('Project management snapshot revision must be a non-negative integer.');
+  }
+  requireSessionGeneration(snapshot, '$snapshot');
+  if (snapshot.goal !== undefined) {
+    requireBoundedString(
+      snapshot.goal,
+      '$snapshot.goal',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
+      true,
+    );
+  }
+  requireBoundedString(
+    snapshot.scratchpad,
+    '$snapshot.scratchpad',
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+  );
+  if (!Array.isArray(snapshot.tasks)) {
+    throw new FlexHarnessStoreFormatError('$snapshot.tasks must be an array.');
+  }
+  if (snapshot.tasks.length > FLEX_PROJECT_MANAGEMENT_LIMITS.maxTasks) {
+    throw new FlexHarnessStoreFormatError('$snapshot.tasks exceeds its task-count limit.');
+  }
+  const taskIds = new Set<string>();
+  for (let index = 0; index < snapshot.tasks.length; index++) {
+    const task = validateTask(snapshot.tasks[index], `$snapshot.tasks[${index}]`);
+    if (taskIds.has(task.id)) {
+      throw new FlexHarnessStoreFormatError(`$snapshot.tasks contains duplicate task "${task.id}".`);
+    }
+    taskIds.add(task.id);
+  }
+  if (Buffer.byteLength(JSON.stringify(snapshot), 'utf8') > FLEX_PROJECT_MANAGEMENT_LIMITS.maxSnapshotBytes) {
+    throw new FlexHarnessStoreFormatError('Project management snapshot exceeds its serialized byte limit.');
+  }
+}
+
+export function assertFlexProjectManagementTombstone(
+  value: unknown,
+): asserts value is IFlexProjectManagementTombstone {
+  assertJsonSerializable(value, '$tombstone');
+  const tombstone = requireRecord(value, '$tombstone');
+  requireOnlyKeys(
+    tombstone,
+    [
+      'schemaVersion',
+      'revision',
+      'sessionGenerationId',
+      'sessionGenerationSequence',
+      'deletedAt',
+    ],
+    '$tombstone',
+  );
+  if (tombstone.schemaVersion !== FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION) {
+    throw new FlexHarnessStoreFormatError(
+      `Project management tombstone schemaVersion must be ${FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION}.`,
+    );
+  }
+  if (!Number.isSafeInteger(tombstone.revision) || Number(tombstone.revision) < 1) {
+    throw new FlexHarnessStoreFormatError(
+      'Project management tombstone revision must be a positive integer.',
+    );
+  }
+  requireSessionGeneration(tombstone, '$tombstone');
+  requireTimestamp(tombstone.deletedAt, '$tombstone.deletedAt');
+}
+
+export function assertFlexProjectManagementRecord(
+  value: unknown,
+): asserts value is TFlexProjectManagementRecord {
+  const record = requireRecord(value, '$record');
+  if (Object.prototype.hasOwnProperty.call(record, 'deletedAt')) {
+    assertFlexProjectManagementTombstone(value);
+  } else {
+    assertFlexProjectManagementSnapshot(value);
+  }
+}