@agent-native/core 0.101.13 → 0.102.0

package/corpus/templates/tasks/server/custom-fields/validate.ts

@@ -0,0 +1,210 @@
+import { UserInputError } from "../errors.js";
+import {
+  SELECT_COLOR_TOKENS,
+  type FieldConfigInput,
+  type FieldDefinition,
+  type FieldType,
+  type FieldValue,
+  type FieldValueInput,
+  type SelectConfigInput,
+} from "./types.js";
+
+export function validateFieldTitle(title: string): void {
+  if (!title.trim()) throw new UserInputError("Field title is required.");
+}
+
+function validatePrecision(precision: number | undefined): void {
+  if (precision === undefined) return;
+  if (!Number.isInteger(precision) || precision < 0 || precision > 6) {
+    throw new UserInputError("precision must be an integer between 0 and 6.");
+  }
+}
+
+function validateSelectColor(color: string | undefined): void {
+  if (color === undefined) return;
+  if (!(SELECT_COLOR_TOKENS as readonly string[]).includes(color)) {
+    throw new UserInputError("Select option color is invalid.");
+  }
+}
+
+function validateSelectConfig(config: SelectConfigInput): void {
+  for (const [index, option] of (config.options ?? []).entries()) {
+    if (!option.name.trim()) {
+      throw new UserInputError(`Select option #${index + 1} name is required.`);
+    }
+    if (option.id?.trim() === "") {
+      throw new UserInputError(
+        `Select option #${index + 1} id cannot be empty.`,
+      );
+    }
+    const sortOrder = option.sortOrder;
+    if (
+      sortOrder !== undefined &&
+      (!Number.isInteger(sortOrder) || sortOrder < 0)
+    ) {
+      throw new UserInputError(
+        `Select option #${index + 1} sortOrder must be a non-negative integer.`,
+      );
+    }
+    validateSelectColor(option.color);
+  }
+}
+
+export function validateFieldConfig<T extends FieldType>(
+  type: T,
+  config?: FieldConfigInput<T>,
+): void {
+  if (type === "text" || type === "rich_text" || type === "date") {
+    return;
+  }
+
+  const input = (config ?? {}) as FieldConfigInput<T>;
+
+  if (type === "number") {
+    const numberConfig = input as FieldConfigInput<"number">;
+    validatePrecision(numberConfig.precision);
+    if (
+      numberConfig.positiveOnly !== undefined &&
+      typeof numberConfig.positiveOnly !== "boolean"
+    ) {
+      throw new UserInputError("positiveOnly must be a boolean.");
+    }
+    return;
+  }
+
+  if (type === "percent") {
+    validatePrecision((input as FieldConfigInput<"percent">).precision);
+    return;
+  }
+
+  if (type === "currency") {
+    const currencyConfig = input as FieldConfigInput<"currency">;
+    if (currencyConfig.symbol !== undefined) {
+      const symbol = currencyConfig.symbol.trim();
+      if (!symbol) throw new UserInputError("Currency symbol is required.");
+      if (symbol.length > 8) {
+        throw new UserInputError(
+          "Currency symbol must be at most 8 characters.",
+        );
+      }
+    }
+    validatePrecision(currencyConfig.precision);
+    return;
+  }
+
+  validateSelectConfig(input as SelectConfigInput);
+}
+
+function assertPrecision(value: number, precision: number): void {
+  const factor = 10 ** precision;
+  const scaled = value * factor;
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(scaled)) * 100;
+  if (Math.abs(scaled - Math.round(scaled)) > tolerance) {
+    throw new UserInputError(
+      precision === 0
+        ? "Value must be a whole number."
+        : `Value must have at most ${precision} decimal places.`,
+    );
+  }
+}
+
+function validateNumericValue(
+  value: number,
+  precision: number,
+  options?: { positiveOnly?: boolean },
+): void {
+  if (!Number.isFinite(value)) {
+    throw new UserInputError("Invalid number value.");
+  }
+  assertPrecision(value, precision);
+  if (options?.positiveOnly && value < 0) {
+    throw new UserInputError("Value must be zero or positive.");
+  }
+}
+
+function validateIsoDate(value: string): void {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new UserInputError("Invalid date value.");
+  }
+  const [year, month, day] = value.split("-").map(Number);
+  const parsed = new Date(Date.UTC(year, month - 1, day));
+  if (
+    parsed.getUTCFullYear() !== year ||
+    parsed.getUTCMonth() !== month - 1 ||
+    parsed.getUTCDate() !== day
+  ) {
+    throw new UserInputError("Invalid date value.");
+  }
+}
+
+function validateSelectValue(
+  field: Extract<FieldDefinition, { type: "single_select" | "multi_select" }>,
+  value: FieldValue,
+): void {
+  const allowed = new Set(field.config.options.map((option) => option.id));
+
+  if (field.type === "single_select") {
+    if (!allowed.has(value as string)) {
+      throw new UserInputError("Select value is not a valid option.");
+    }
+    return;
+  }
+
+  const unique = [...new Set(value as string[])];
+  for (const optionId of unique) {
+    if (!allowed.has(optionId)) {
+      throw new UserInputError("Select value is not a valid option.");
+    }
+  }
+}
+
+export function validateFieldValue(
+  field: FieldDefinition,
+  value: FieldValueInput,
+): void {
+  switch (field.type) {
+    case "text":
+    case "rich_text":
+      if (typeof value !== "string") {
+        throw new UserInputError("Invalid text value.");
+      }
+      return;
+    case "number":
+      if (typeof value !== "number") {
+        throw new UserInputError("Invalid number value.");
+      }
+      validateNumericValue(value, field.config.precision ?? 0, {
+        positiveOnly: field.config.positiveOnly,
+      });
+      return;
+    case "percent":
+      if (typeof value !== "number") {
+        throw new UserInputError("Invalid number value.");
+      }
+      validateNumericValue(value, field.config.precision ?? 0);
+      return;
+    case "currency":
+      if (typeof value !== "number") {
+        throw new UserInputError("Invalid number value.");
+      }
+      validateNumericValue(value, field.config.precision ?? 2);
+      return;
+    case "date":
+      if (typeof value !== "string") {
+        throw new UserInputError("Invalid date value.");
+      }
+      validateIsoDate(value);
+      return;
+    case "single_select":
+      if (typeof value !== "string") {
+        throw new UserInputError("Invalid select value.");
+      }
+      validateSelectValue(field, value);
+      return;
+    case "multi_select":
+      if (!Array.isArray(value)) {
+        throw new UserInputError("Invalid select value.");
+      }
+      validateSelectValue(field, value);
+  }
+}

package/corpus/templates/tasks/server/custom-fields/values/store.ts

@@ -0,0 +1,386 @@
+import { and, eq, inArray, sql, type SQL } from "drizzle-orm";
+
+import { caseById, chunk } from "../../db/bulk-write.js";
+import { getDb } from "../../db/index.js";
+import { createRecordId, timestamp } from "../../db/record-utils.js";
+import {
+  customFields,
+  customFieldValues,
+  type StoredCustomFieldValue,
+} from "../../db/schema.js";
+import type { DbHandle } from "../../db/transaction.js";
+import { NotFoundError, UserInputError } from "../../errors.js";
+import { getStoredItem } from "../../stored-items/store.js";
+import { isEmptyFieldValue, normalizeFieldValue } from "../normalize.js";
+import {
+  parseField,
+  parseStoredValue,
+  parseFieldValueShape,
+} from "../parse.js";
+import type { FieldDefinition, FieldValue, FieldValueInput } from "../types.js";
+import { validateFieldValue } from "../validate.js";
+
+export type { FieldValue, FieldValueInput } from "../types.js";
+
+export type PreparedFieldValuePatch = {
+  field: FieldDefinition;
+  value: FieldValue | null;
+};
+
+export async function prepareCustomFieldValuePatches(
+  input: {
+    ownerEmail: string;
+    taskId: string;
+    values: Array<{ fieldId: string; value: FieldValueInput }>;
+  },
+  db: DbHandle = getDb(),
+): Promise<Map<string, PreparedFieldValuePatch>> {
+  if (input.values.length === 0) {
+    return new Map();
+  }
+
+  const task = await getStoredItem(
+    {
+      ownerEmail: input.ownerEmail,
+      id: input.taskId,
+      promotedToTask: true,
+    },
+    db,
+  );
+  if (!task) throw new NotFoundError("Task not found.");
+
+  const fields = await db
+    .select()
+    .from(customFields)
+    .where(
+      and(
+        eq(customFields.ownerEmail, input.ownerEmail),
+        inArray(
+          customFields.id,
+          input.values.map((value) => value.fieldId),
+        ),
+      ),
+    );
+
+  const fieldsById = new Map(
+    fields.map((field) => [field.id, parseField(field)]),
+  );
+  const normalizedValues = new Map<string, PreparedFieldValuePatch>();
+  for (const value of input.values) {
+    const field = fieldsById.get(value.fieldId);
+    if (!field) throw new NotFoundError("Custom field not found.");
+    let normalizedValue: FieldValue | null;
+    const shaped = parseFieldValueShape(value.value);
+    if (isEmptyFieldValue(shaped)) {
+      normalizedValue = null;
+    } else {
+      validateFieldValue(field, shaped);
+      normalizedValue = normalizeFieldValue(field, shaped);
+    }
+    normalizedValues.set(value.fieldId, {
+      field,
+      value: normalizedValue,
+    });
+  }
+
+  return normalizedValues;
+}
+
+export async function applyCustomFieldValuePatches(
+  input: {
+    ownerEmail: string;
+    taskId: string;
+    patches: Map<string, PreparedFieldValuePatch>;
+    updatedAt: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<void> {
+  const patches = [...input.patches.values()];
+  const clearedFieldIds = patches
+    .filter((patch) => patch.value === null)
+    .map((patch) => patch.field.id);
+  const rows = patches
+    .filter((patch) => patch.value !== null)
+    .map((patch) => ({
+      id: createRecordId("cfv"),
+      fieldId: patch.field.id,
+      taskId: input.taskId,
+      valueJson: JSON.stringify(patch.value),
+      ownerEmail: input.ownerEmail,
+      createdAt: input.updatedAt,
+      updatedAt: input.updatedAt,
+    }));
+
+  if (clearedFieldIds.length > 0) {
+    await db
+      .delete(customFieldValues)
+      .where(
+        and(
+          eq(customFieldValues.ownerEmail, input.ownerEmail),
+          eq(customFieldValues.taskId, input.taskId),
+          inArray(customFieldValues.fieldId, clearedFieldIds),
+        ),
+      );
+  }
+
+  for (const group of chunk(rows)) {
+    await db
+      .insert(customFieldValues)
+      .values(group)
+      .onConflictDoUpdate({
+        target: [
+          customFieldValues.ownerEmail,
+          customFieldValues.taskId,
+          customFieldValues.fieldId,
+        ],
+        set: {
+          valueJson: sql`excluded.value_json`,
+          updatedAt: input.updatedAt,
+        },
+      });
+  }
+}
+
+export async function getCustomFieldValue(
+  input: {
+    ownerEmail: string;
+    taskId: string;
+    fieldId: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<FieldValue | null> {
+  const [row] = await db
+    .select()
+    .from(customFieldValues)
+    .where(
+      and(
+        eq(customFieldValues.ownerEmail, input.ownerEmail),
+        eq(customFieldValues.taskId, input.taskId),
+        eq(customFieldValues.fieldId, input.fieldId),
+      ),
+    )
+    .limit(1);
+  if (!row) return null;
+
+  const [fieldRow] = await db
+    .select()
+    .from(customFields)
+    .where(
+      and(
+        eq(customFields.ownerEmail, input.ownerEmail),
+        eq(customFields.id, input.fieldId),
+      ),
+    )
+    .limit(1);
+  if (!fieldRow) throw new NotFoundError("Custom field not found.");
+
+  return parseStoredValue(parseField(fieldRow), row);
+}
+
+export async function listCustomFieldValues(
+  input: {
+    ownerEmail: string;
+    ids?: string[];
+    taskIds?: string[];
+    fieldIds?: string[];
+  },
+  db: DbHandle = getDb(),
+): Promise<StoredCustomFieldValue[]> {
+  const selector = buildValueSelector(input);
+  if (!selector) {
+    throw new UserInputError(
+      "Provide ids, taskIds, or fieldIds to list custom field values.",
+    );
+  }
+  if (selector.selectsNothing) return [];
+
+  return db
+    .select()
+    .from(customFieldValues)
+    .where(and(...selector.conditions));
+}
+
+export async function updateCustomFieldValues(
+  input: {
+    ownerEmail: string;
+    entries: Array<{ id: string; value: FieldValue }>;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<void> {
+  if (input.entries.length === 0) return;
+
+  const updatedAt = timestamp(input.now);
+  const entries = input.entries.map((entry) => ({
+    id: entry.id,
+    value: JSON.stringify(entry.value),
+  }));
+
+  for (const group of chunk(entries)) {
+    await db
+      .update(customFieldValues)
+      .set({ valueJson: caseById(customFieldValues.id, group), updatedAt })
+      .where(
+        and(
+          eq(customFieldValues.ownerEmail, input.ownerEmail),
+          inArray(
+            customFieldValues.id,
+            group.map((entry) => entry.id),
+          ),
+        ),
+      );
+  }
+}
+
+export async function updateCustomFieldValue(
+  input: {
+    ownerEmail: string;
+    id: string;
+    value: FieldValue;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<void> {
+  await updateCustomFieldValues(
+    {
+      ownerEmail: input.ownerEmail,
+      entries: [{ id: input.id, value: input.value }],
+      now: input.now,
+    },
+    db,
+  );
+}
+
+/** Upsert a task's values by field id; an empty value clears the stored row. */
+export async function updateCustomFieldValuesByTaskId(
+  input: {
+    ownerEmail: string;
+    taskId: string;
+    values: Array<{ fieldId: string; value: FieldValueInput }>;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<void> {
+  const patches = await prepareCustomFieldValuePatches(input, db);
+  if (patches.size === 0) return;
+
+  const updatedAt = timestamp(input.now);
+  await db.transaction(async (tx) => {
+    await applyCustomFieldValuePatches(
+      {
+        ownerEmail: input.ownerEmail,
+        taskId: input.taskId,
+        patches,
+        updatedAt,
+      },
+      tx,
+    );
+  });
+}
+
+export async function deleteCustomFieldValues(
+  input: { ownerEmail: string; ids: string[] },
+  db: DbHandle = getDb(),
+): Promise<{ deletedValues: number }> {
+  const ids = [...new Set(input.ids)];
+  if (ids.length === 0) return { deletedValues: 0 };
+
+  let deletedValues = 0;
+  for (const group of chunk(ids)) {
+    const result = await deleteValuesWhere(
+      input.ownerEmail,
+      [inArray(customFieldValues.id, group)],
+      db,
+    );
+    deletedValues += result.deletedValues;
+  }
+  return { deletedValues };
+}
+
+export async function deleteCustomFieldValue(
+  input: { ownerEmail: string; id: string },
+  db: DbHandle = getDb(),
+): Promise<{ deletedValues: number }> {
+  return deleteCustomFieldValues(
+    { ownerEmail: input.ownerEmail, ids: [input.id] },
+    db,
+  );
+}
+
+export async function deleteCustomFieldValuesByTaskIds(
+  input: { ownerEmail: string; taskIds: string[] },
+  db: DbHandle = getDb(),
+): Promise<{ deletedValues: number }> {
+  const taskIds = [...new Set(input.taskIds)];
+  if (taskIds.length === 0) return { deletedValues: 0 };
+
+  return deleteValuesWhere(
+    input.ownerEmail,
+    [inArray(customFieldValues.taskId, taskIds)],
+    db,
+  );
+}
+
+export async function deleteCustomFieldValuesByFieldIds(
+  input: { ownerEmail: string; fieldIds: string[] },
+  db: DbHandle = getDb(),
+): Promise<{ deletedValues: number }> {
+  const fieldIds = [...new Set(input.fieldIds)];
+  if (fieldIds.length === 0) return { deletedValues: 0 };
+
+  return deleteValuesWhere(
+    input.ownerEmail,
+    [inArray(customFieldValues.fieldId, fieldIds)],
+    db,
+  );
+}
+
+function buildValueSelector(input: {
+  ownerEmail: string;
+  ids?: string[];
+  taskIds?: string[];
+  fieldIds?: string[];
+}): { conditions: SQL[]; selectsNothing: boolean } | null {
+  const ids = input.ids ? [...new Set(input.ids)] : undefined;
+  const taskIds = input.taskIds ? [...new Set(input.taskIds)] : undefined;
+  const fieldIds = input.fieldIds ? [...new Set(input.fieldIds)] : undefined;
+  if (!ids && !taskIds && !fieldIds) return null;
+
+  // An explicit empty id list selects nothing; without this it would fall
+  // through to matching every value the owner has.
+  const selectsNothing =
+    ids?.length === 0 || taskIds?.length === 0 || fieldIds?.length === 0;
+
+  const conditions: SQL[] = [
+    eq(customFieldValues.ownerEmail, input.ownerEmail),
+  ];
+  if (ids?.length) conditions.push(inArray(customFieldValues.id, ids));
+  if (taskIds?.length)
+    conditions.push(inArray(customFieldValues.taskId, taskIds));
+  if (fieldIds?.length)
+    conditions.push(inArray(customFieldValues.fieldId, fieldIds));
+
+  return { conditions, selectsNothing };
+}
+
+async function deleteValuesWhere(
+  ownerEmail: string,
+  selectors: SQL[],
+  db: DbHandle,
+): Promise<{ deletedValues: number }> {
+  const conditions = [
+    eq(customFieldValues.ownerEmail, ownerEmail),
+    ...selectors,
+  ];
+
+  const values = await db
+    .select({ id: customFieldValues.id })
+    .from(customFieldValues)
+    .where(and(...conditions));
+
+  if (values.length > 0) {
+    await db.delete(customFieldValues).where(and(...conditions));
+  }
+
+  return { deletedValues: values.length };
+}

package/corpus/templates/tasks/server/db/bulk-write.ts

@@ -0,0 +1,30 @@
+import { sql, type Column, type SQL } from "drizzle-orm";
+
+export type CaseEntry<T> = { id: string; value: T };
+
+/** `CASE <id> WHEN 'a' THEN … END` — writes a different value per row in one statement. */
+export function caseById<T>(idColumn: Column, entries: CaseEntry<T>[]): SQL<T> {
+  const whens = entries.map(
+    (entry) => sql`when ${entry.id} then ${entry.value}`,
+  );
+  return sql`case ${idColumn} ${sql.join(whens, sql` `)} end`;
+}
+
+/**
+ * An entry costs three bind parameters (id and value in the CASE, id again in
+ * the IN list). Reorder and field cleanup rewrite every row an owner has, which
+ * `BULK_ID_LIMIT` does not cap, so the work is chunked to stay under SQLite's
+ * 999-parameter default.
+ */
+export const BULK_WRITE_CHUNK_SIZE = 200;
+
+export function chunk<T>(
+  items: T[],
+  size: number = BULK_WRITE_CHUNK_SIZE,
+): T[][] {
+  const chunks: T[][] = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}

package/corpus/templates/tasks/server/db/index.ts

@@ -0,0 +1,5 @@
+import { createGetDb } from "@agent-native/core/db";
+
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);

package/corpus/templates/tasks/server/db/record-utils.ts

@@ -0,0 +1,7 @@
+export function createRecordId(prefix: string): string {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+export function timestamp(input?: string): string {
+  return input ?? new Date().toISOString();
+}

package/corpus/templates/tasks/server/db/schema.ts

@@ -0,0 +1,67 @@
+import {
+  integer,
+  now,
+  table,
+  text,
+  uniqueIndex,
+} from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  promotedToTask: integer("promoted_to_task", { mode: "boolean" })
+    .notNull()
+    .default(true),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export type StoredItem = typeof tasks.$inferSelect;
+export type NewStoredItem = typeof tasks.$inferInsert;
+
+export const customFields = table("custom_fields", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  type: text("type").notNull(),
+  configJson: text("config_json").notNull(),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const customFieldValues = table(
+  "custom_field_values",
+  {
+    id: text("id").primaryKey(),
+    fieldId: text("field_id").notNull(),
+    taskId: text("task_id").notNull(),
+    valueJson: text("value_json").notNull(),
+    ownerEmail: text("owner_email").notNull(),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+  (values) => ({
+    uniqueTaskField: uniqueIndex(
+      "idx_custom_field_values_unique_task_field",
+    ).on(values.ownerEmail, values.taskId, values.fieldId),
+  }),
+);
+
+export const userConfig = table("user_config", {
+  ownerEmail: text("owner_email").primaryKey(),
+  taskCardFieldIdsJson: text("task_card_field_ids_json")
+    .notNull()
+    .default("[]"),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export type StoredCustomField = typeof customFields.$inferSelect;
+export type NewCustomField = typeof customFields.$inferInsert;
+export type StoredCustomFieldValue = typeof customFieldValues.$inferSelect;
+export type NewCustomFieldValue = typeof customFieldValues.$inferInsert;
+export type StoredUserConfig = typeof userConfig.$inferSelect;
+export type NewUserConfig = typeof userConfig.$inferInsert;