@agent-native/core 0.101.14 → 0.102.1

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

@@ -0,0 +1,163 @@
+import { UserInputError } from "../errors.js";
+/**
+ * Canonicalize validated configs for storage (select option ids and sort order).
+ * Shape validation lives in schema.ts; domain rules in validate.ts.
+ */
+import type {
+  FieldConfig,
+  FieldDefinition,
+  FieldType,
+  SelectConfigInput,
+  SelectOption,
+  SelectOptionInput,
+  FieldConfigInput,
+  FieldValue,
+  FieldValueInput,
+} from "./types.js";
+
+const SORT_GAP = 1000;
+
+export function isEmptyFieldValue(value: FieldValueInput): boolean {
+  return (
+    value === null ||
+    value === "" ||
+    (Array.isArray(value) && value.length === 0)
+  );
+}
+
+export function normalizeFieldTitle(title: string): string {
+  return title.trim();
+}
+
+export function normalizeFieldConfigInput<T extends FieldType>(
+  type: T,
+  config?: FieldConfigInput<T>,
+): FieldConfigInput<T> {
+  if (type === "text" || type === "rich_text" || type === "date") {
+    return {} as FieldConfigInput<T>;
+  }
+
+  const input = (config ?? {}) as FieldConfigInput<T>;
+
+  if (type === "number") {
+    const numberConfig = input as FieldConfigInput<"number">;
+    return {
+      precision: numberConfig.precision ?? 0,
+      ...(numberConfig.positiveOnly !== undefined
+        ? { positiveOnly: numberConfig.positiveOnly }
+        : {}),
+    } as FieldConfigInput<T>;
+  }
+
+  if (type === "percent") {
+    const percentConfig = input as FieldConfigInput<"percent">;
+    return {
+      precision: percentConfig.precision ?? 0,
+    } as FieldConfigInput<T>;
+  }
+
+  if (type === "currency") {
+    const currencyConfig = input as FieldConfigInput<"currency">;
+    return {
+      symbol:
+        currencyConfig.symbol === undefined
+          ? "$"
+          : currencyConfig.symbol.trim(),
+      precision: currencyConfig.precision ?? 2,
+    } as FieldConfigInput<T>;
+  }
+
+  const selectConfig = input as SelectConfigInput;
+  return {
+    options: (selectConfig.options ?? []).map((option) => {
+      const id = option.id?.trim();
+      return {
+        ...(id ? { id } : {}),
+        name: option.name.trim(),
+        ...(option.color !== undefined ? { color: option.color } : {}),
+        ...(option.sortOrder !== undefined
+          ? { sortOrder: option.sortOrder }
+          : {}),
+      };
+    }),
+  } as FieldConfigInput<T>;
+}
+
+function optionIdFor(optionName: string) {
+  return `opt_${
+    optionName
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, "") || crypto.randomUUID()
+  }`;
+}
+
+function canonicalizeSelectOptions(
+  options: SelectOptionInput[],
+): SelectOption[] {
+  const names = new Set<string>();
+  const ids = new Set<string>();
+  return options
+    .map((option, index) => {
+      const name = option.name.trim();
+      const key = name.toLowerCase();
+      if (names.has(key)) {
+        throw new UserInputError(`Select option "${name}" is duplicated.`);
+      }
+      names.add(key);
+      const providedId = option.id?.trim();
+      const baseId = providedId || optionIdFor(name);
+      let optionId = baseId;
+      let suffix = 2;
+      while (ids.has(optionId)) {
+        if (providedId) {
+          throw new UserInputError(
+            `Select option id "${providedId}" is duplicated.`,
+          );
+        }
+        optionId = `${baseId}_${suffix}`;
+        suffix += 1;
+      }
+      ids.add(optionId);
+      return {
+        id: optionId,
+        name,
+        color: option.color,
+        sortOrder: option.sortOrder ?? index * SORT_GAP,
+      } satisfies SelectOption;
+    })
+    .sort((a, b) => a.sortOrder - b.sortOrder || a.name.localeCompare(b.name));
+}
+
+export function canonicalizeFieldConfig<T extends FieldType>(
+  type: T,
+  config: FieldConfigInput<T>,
+): FieldConfig {
+  if (type === "single_select" || type === "multi_select") {
+    const selectConfig = config as SelectConfigInput;
+    return { options: canonicalizeSelectOptions(selectConfig.options) };
+  }
+
+  return config as FieldConfig;
+}
+
+export function normalizeFieldValue(
+  field: FieldDefinition,
+  value: FieldValueInput,
+): FieldValue {
+  switch (field.type) {
+    case "text":
+    case "rich_text":
+    case "date":
+    case "number":
+    case "percent":
+    case "currency":
+    case "single_select":
+      return value as FieldValue;
+    case "multi_select": {
+      const allowedIds = field.config.options.map((option) => option.id);
+      const unique = [...new Set(value as string[])];
+      return allowedIds.filter((optionId) => unique.includes(optionId));
+    }
+  }
+}

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

@@ -0,0 +1,146 @@
+/**
+ * Read path: DB rows (JSON columns) → typed field definitions and values.
+ * Structural parsing uses schema.ts; domain rules use validate.ts; then normalize.
+ */
+import type {
+  StoredCustomField,
+  StoredCustomFieldValue,
+} from "../db/schema.js";
+import {
+  canonicalizeFieldConfig,
+  isEmptyFieldValue,
+  normalizeFieldConfigInput,
+  normalizeFieldValue,
+} from "./normalize.js";
+import {
+  emptyConfigShapeSchema,
+  currencyConfigShapeSchema,
+  fieldTypeSchema,
+  fieldValueInputSchema,
+  numericConfigShapeSchema,
+  percentConfigShapeSchema,
+  selectConfigShapeSchema,
+} from "./schema.js";
+import type {
+  FieldConfigInput,
+  FieldDefinition,
+  FieldType,
+  FieldValue,
+  FieldValueInput,
+} from "./types.js";
+import { validateFieldConfig, validateFieldValue } from "./validate.js";
+
+export function parseFieldType(value: unknown): FieldType {
+  return fieldTypeSchema.parse(value);
+}
+
+export function parseFieldConfigShape<T extends FieldType>(
+  type: T,
+  config: unknown,
+): FieldConfigInput<T> {
+  if (type === "text" || type === "rich_text" || type === "date") {
+    emptyConfigShapeSchema.parse(config ?? {});
+    return {} as FieldConfigInput<T>;
+  }
+
+  if (type === "number") {
+    return numericConfigShapeSchema.parse(config ?? {}) as FieldConfigInput<T>;
+  }
+
+  if (type === "percent") {
+    return percentConfigShapeSchema.parse(config ?? {}) as FieldConfigInput<T>;
+  }
+
+  if (type === "currency") {
+    return currencyConfigShapeSchema.parse(config ?? {}) as FieldConfigInput<T>;
+  }
+
+  return selectConfigShapeSchema.parse(config ?? {}) as FieldConfigInput<T>;
+}
+
+export function parseFieldValueShape(value: unknown): FieldValueInput {
+  return fieldValueInputSchema.parse(value);
+}
+
+export function parseField(row: StoredCustomField): FieldDefinition {
+  const type = parseFieldType(row.type);
+  const shaped = parseFieldConfigShape(type, JSON.parse(row.configJson));
+  validateFieldConfig(type, shaped);
+  const config = canonicalizeFieldConfig(
+    type,
+    normalizeFieldConfigInput(type, shaped),
+  );
+  return {
+    id: row.id,
+    title: row.title,
+    sortOrder: row.sortOrder,
+    ownerEmail: row.ownerEmail,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    type,
+    config,
+  } as FieldDefinition;
+}
+
+export function parseStoredValue(
+  field: FieldDefinition,
+  row: StoredCustomFieldValue,
+): FieldValue | null {
+  let shaped: FieldValueInput;
+  try {
+    shaped = parseFieldValueShape(JSON.parse(row.valueJson));
+  } catch {
+    return null;
+  }
+  if (isEmptyFieldValue(shaped)) return null;
+
+  const coerced = coerceStoredValueToConfig(field, shaped);
+  if (coerced === null || isEmptyFieldValue(coerced)) return null;
+
+  try {
+    validateFieldValue(field, coerced);
+  } catch {
+    return null;
+  }
+  return normalizeFieldValue(field, coerced);
+}
+
+function roundToPrecision(value: number, precision: number): number {
+  const factor = 10 ** precision;
+  return Math.round(value * factor) / factor;
+}
+
+function coerceStoredValueToConfig(
+  field: FieldDefinition,
+  value: FieldValueInput,
+): FieldValueInput | null {
+  switch (field.type) {
+    case "number": {
+      if (typeof value !== "number" || !Number.isFinite(value)) return null;
+      const rounded = roundToPrecision(value, field.config.precision ?? 0);
+      if (field.config.positiveOnly && rounded < 0) return null;
+      return rounded;
+    }
+    case "percent":
+      if (typeof value !== "number" || !Number.isFinite(value)) return null;
+      return roundToPrecision(value, field.config.precision ?? 0);
+    case "currency":
+      if (typeof value !== "number" || !Number.isFinite(value)) return null;
+      return roundToPrecision(value, field.config.precision ?? 2);
+    case "single_select": {
+      const allowed = field.config.options.some(
+        (option) => option.id === value,
+      );
+      return allowed ? value : null;
+    }
+    case "multi_select": {
+      if (!Array.isArray(value)) return null;
+      const allowed = new Set(field.config.options.map((option) => option.id));
+      return value.filter(
+        (id): id is string => typeof id === "string" && allowed.has(id),
+      );
+    }
+    default:
+      return value;
+  }
+}

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

@@ -0,0 +1,147 @@
+import { z } from "zod";
+
+import { FIELD_TYPES, SELECT_COLOR_TOKENS } from "./types.js";
+
+/** Parse JSON-string action args before Zod validation. */
+export function parseJsonArg(value: unknown) {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  return JSON.parse(trimmed);
+}
+
+export const fieldTypeSchema = z.enum(FIELD_TYPES);
+export const selectColorSchema = z.enum(SELECT_COLOR_TOKENS);
+
+export const emptyConfigShapeSchema = z.object({}).strict();
+export const numericConfigShapeSchema = z
+  .object({
+    precision: z.number().optional(),
+    positiveOnly: z.boolean().optional(),
+  })
+  .strict();
+export const percentConfigShapeSchema = z
+  .object({
+    precision: z.number().optional(),
+  })
+  .strict();
+export const currencyConfigShapeSchema = z
+  .object({
+    symbol: z.string().optional(),
+    precision: z.number().optional(),
+  })
+  .strict();
+export const selectOptionShapeSchema = z
+  .object({
+    id: z.string().optional(),
+    name: z.string(),
+    color: selectColorSchema.optional(),
+    sortOrder: z.number().optional(),
+  })
+  .strict();
+export const selectConfigShapeSchema = z
+  .object({
+    options: z.array(selectOptionShapeSchema).optional(),
+  })
+  .strict();
+export const fieldConfigShapeSchema = z.union([
+  selectConfigShapeSchema,
+  currencyConfigShapeSchema,
+  numericConfigShapeSchema,
+  percentConfigShapeSchema,
+  emptyConfigShapeSchema,
+]);
+export const fieldValueInputSchema = z.union([
+  z.string(),
+  z.number(),
+  z.array(z.string()),
+  z.null(),
+]);
+
+export type {
+  CurrencyConfigInput,
+  EmptyConfigInput,
+  FieldConfigInput,
+  NumericConfigInput,
+  PercentConfigInput,
+  SelectConfigInput,
+  SelectOptionInput,
+} from "./types.js";
+
+function configArg<T extends z.ZodType>(schema: T) {
+  return z.preprocess(parseJsonArg, schema).optional();
+}
+
+const titleShapeSchema = z.string().describe("Field title");
+
+const createCustomFieldUnion = z.discriminatedUnion("type", [
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("text"),
+    config: configArg(emptyConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("rich_text"),
+    config: configArg(emptyConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("date"),
+    config: configArg(emptyConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("number"),
+    config: configArg(numericConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("percent"),
+    config: configArg(percentConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("currency"),
+    config: configArg(currencyConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("single_select"),
+    config: configArg(selectConfigShapeSchema),
+  }),
+  z.object({
+    title: titleShapeSchema,
+    type: z.literal("multi_select"),
+    config: configArg(selectConfigShapeSchema),
+  }),
+]);
+
+/**
+ * Agent-tool layer registers requires top-level object.
+ * The refinement delegates to the discriminated union so config is still validated per type.
+ */
+export const createCustomFieldActionSchema = z
+  .object({
+    title: titleShapeSchema,
+    type: fieldTypeSchema.describe("Field type; immutable after creation"),
+    config: configArg(z.unknown()).describe(
+      "Type-compatible field configuration",
+    ),
+  })
+  .superRefine((val, ctx) => {
+    const result = createCustomFieldUnion.safeParse(val);
+    if (result.success) return;
+    for (const issue of result.error.issues) {
+      ctx.addIssue({
+        code: "custom",
+        path: issue.path,
+        message: issue.message,
+      });
+    }
+  });
+
+export const updateCustomFieldConfigActionSchema = z.preprocess(
+  parseJsonArg,
+  z.unknown(),
+);