@kernhq/module-tracker 0.1.2 → 0.2.0

package/dist/server/services/values.js

@@ -0,0 +1,172 @@
+import { KernError } from '@kernhq/kernel';
+/**
+ * A source that is allowed to produce an incomplete issue.
+ *
+ * A customer replying to a support address does not know the workspace made "Impact" required. If
+ * required fields were enforced on that path, the mail would bounce and the request would be lost —
+ * so inbound sources record the gap and carry on, and a human completes the issue afterwards.
+ */
+const LENIENT_SOURCES = new Set(['email', 'intake', 'import', 'automation']);
+const isBlank = (v) => v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0);
+const asArray = (v) => (Array.isArray(v) ? v : [v]);
+/**
+ * Validates one value against its field definition. Pure: every lookup it needs is passed in, so
+ * it can be unit-tested and called in a loop without touching the database.
+ */
+export function checkValue(def, value, ctx = {}) {
+    if (isBlank(value))
+        return null;
+    const cfg = def.config ?? {};
+    switch (def.type) {
+        case 'number':
+        case 'formula': {
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                return 'Expected a number';
+            if (cfg.min !== undefined && value < cfg.min)
+                return `Must be at least ${cfg.min}`;
+            if (cfg.max !== undefined && value > cfg.max)
+                return `Must be at most ${cfg.max}`;
+            if (cfg.precision !== undefined) {
+                const scaled = value * 10 ** cfg.precision;
+                if (Math.abs(scaled - Math.round(scaled)) > 1e-9)
+                    return cfg.precision === 0
+                        ? 'Must be a whole number'
+                        : `Must have at most ${cfg.precision} decimal places`;
+            }
+            return null;
+        }
+        case 'text':
+        case 'textarea': {
+            if (typeof value !== 'string')
+                return 'Expected text';
+            if (cfg.maxLength !== undefined && value.length > cfg.maxLength)
+                return `Must be ${cfg.maxLength} characters or fewer`;
+            if (cfg.pattern) {
+                // The pattern is validated when the field is saved, so a bad one cannot reach here. If one
+                // somehow does, refuse the value rather than throwing an unhandled SyntaxError on a write.
+                try {
+                    if (!new RegExp(cfg.pattern).test(value))
+                        return 'Does not match the required format';
+                }
+                catch {
+                    return 'The field has an invalid pattern — ask an administrator to correct it';
+                }
+            }
+            return null;
+        }
+        case 'date':
+        case 'datetime': {
+            if (typeof value !== 'string' || Number.isNaN(Date.parse(value)))
+                return 'Expected a date in ISO format';
+            return null;
+        }
+        case 'checkbox':
+            return typeof value === 'boolean' ? null : 'Expected true or false';
+        case 'url': {
+            if (typeof value !== 'string')
+                return 'Expected a URL';
+            let parsed;
+            try {
+                parsed = new URL(value);
+            }
+            catch {
+                return 'Expected a valid URL';
+            }
+            // Anything else — `javascript:`, `data:` — becomes a click target in the interface.
+            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+                return 'Only http and https links are allowed';
+            return null;
+        }
+        case 'select':
+        case 'multiselect':
+        case 'label': {
+            const values = def.type === 'select' ? [value] : asArray(value);
+            const allowed = ctx.optionIds ?? new Set(def.options.filter((o) => !o.archived).map((o) => o.id));
+            for (const v of values) {
+                if (typeof v !== 'string')
+                    return 'Expected an option id';
+                if (!allowed.has(v))
+                    return 'Not one of the available options';
+            }
+            return null;
+        }
+        case 'user':
+        case 'multiuser': {
+            const values = def.type === 'user' ? [value] : asArray(value);
+            for (const v of values) {
+                if (typeof v !== 'string')
+                    return 'Expected a user id';
+                if (ctx.memberIds && !ctx.memberIds.has(v))
+                    return 'Not a member of this workspace';
+            }
+            return null;
+        }
+        case 'relation': {
+            // Always an array, whatever `relationMultiple` says — see the KQL compiler, which relies on it.
+            const values = asArray(value);
+            if (cfg.relationMultiple === false && values.length > 1)
+                return 'Only one item may be linked';
+            for (const v of values)
+                if (typeof v !== 'string')
+                    return 'Expected an issue id';
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Turns a submitted `custom` patch into the object to store.
+ *
+ * On create it starts empty and applies defaults; on update it merges into what is already there,
+ * where an explicit `null` deletes a key. Unknown keys are refused either way — silently dropping
+ * one makes a typo look like a field that does not save.
+ */
+export async function normaliseCustom(args) {
+    const byKey = new Map(args.fields.map((f) => [f.key, f]));
+    const out = args.mode === 'create' ? {} : { ...(args.current ?? {}) };
+    const problems = [];
+    let members;
+    let membersLoaded = false;
+    for (const [key, value] of Object.entries(args.patch ?? {})) {
+        const def = byKey.get(key);
+        if (!def)
+            throw KernError.badRequest(`Unknown custom field "${key}"`, { field: `cf.${key}` });
+        if (value === null) {
+            delete out[key];
+            continue;
+        }
+        if ((def.type === 'user' || def.type === 'multiuser') && args.memberIds && !membersLoaded) {
+            members = await args.memberIds();
+            membersLoaded = true;
+        }
+        const problem = checkValue(def, value, { memberIds: members });
+        if (problem)
+            throw KernError.badRequest(problem, { field: `cf.${key}` });
+        out[key] = value;
+    }
+    if (args.mode === 'create')
+        for (const def of args.fields)
+            if (out[def.key] === undefined && def.defaultValue != null)
+                out[def.key] = def.defaultValue;
+    const lenient = LENIENT_SOURCES.has(args.source);
+    // On update, judge only the fields this patch touched. An issue created leniently — a customer
+    // email with no "Impact" — can still be edited; what cannot happen is *clearing* a required
+    // field, which touches it and so is caught.
+    const touched = new Set(Object.keys(args.patch ?? {}));
+    for (const def of args.fields) {
+        const fieldId = `cf.${def.key}`;
+        if (args.mode === 'update' && !touched.has(def.key))
+            continue;
+        const required = args.requiredFieldIds ? args.requiredFieldIds.has(fieldId) : def.required;
+        if (!required || !isBlank(out[def.key]))
+            continue;
+        const message = `"${def.name}" is required`;
+        if (lenient)
+            problems.push({ fieldId, message });
+        else
+            throw KernError.badRequest(message, { field: fieldId });
+    }
+    return { custom: out, skipped: problems };
+}
+//# sourceMappingURL=values.js.map

package/dist/server/services/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../../../src/server/services/values.ts"],"names":[],"mappings":"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"}

package/migrations/0002_field_keys_unique.sql

@@ -0,0 +1,35 @@
+-- A custom field's key is the key it writes into `issues.custom`, so two field definitions that
+-- share a key share a value — whatever their project scope. Until now two partial unique indexes
+-- allowed exactly that: a workspace-level `severity` and a project-scoped `severity` could coexist
+-- and then silently overwrite each other on every issue in that project.
+--
+-- The fix is one unique constraint over (workspace_id, key). Project scope still decides where a
+-- field is *visible*; it no longer decides what it is *called*.
+--
+-- Refuse to run if the data already contains a collision. Merging two fields means choosing which
+-- definition wins and what happens to the values under the loser, and that is not a decision a
+-- migration may take on an operator's behalf.
+do $$
+declare
+  conflict text;
+begin
+  select string_agg(format('%s (%s definitions)', key, n), ', ' order by key)
+    into conflict
+    from (
+      select key, count(*) as n
+        from "mod_tracker"."field_defs"
+       group by workspace_id, key
+      having count(*) > 1
+    ) dupes;
+
+  if conflict is not null then
+    raise exception
+      'tracker: cannot apply 0002_field_keys_unique — duplicate field keys exist: %', conflict
+      using hint =
+        'Rename or delete the duplicates so each key appears once per workspace, then migrate again.';
+  end if;
+end $$;
+--> statement-breakpoint
+DROP INDEX IF EXISTS "mod_tracker"."field_defs_ws_project_key_uq";--> statement-breakpoint
+DROP INDEX IF EXISTS "mod_tracker"."field_defs_ws_key_uq";--> statement-breakpoint
+CREATE UNIQUE INDEX "field_defs_ws_key_uq" ON "mod_tracker"."field_defs" USING btree ("workspace_id","key");

package/migrations/0003_drop_field_schemes.sql

@@ -0,0 +1,9 @@
+-- Field schemes are gone. A project used to gate its custom fields twice: once through a field
+-- scheme, and once through the per-work-item-type field layout that this release makes real. With
+-- both in place a field disappears when *either* gate says so, and nobody can predict which one did
+-- it. The layout is the more useful of the two — it also orders fields and marks them required — so
+-- the scheme goes.
+--
+-- Type schemes and workflow schemes stay: they answer different questions.
+ALTER TABLE "mod_tracker"."projects" DROP COLUMN IF EXISTS "field_scheme_id";--> statement-breakpoint
+DROP TABLE IF EXISTS "mod_tracker"."field_schemes";

package/migrations/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1787397066443,
       "tag": "0001_rls",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1787397066444,
+      "tag": "0002_field_keys_unique",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1787397066445,
+      "tag": "0003_drop_field_schemes",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-tracker",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Kern tracker module: projects, work item types, custom fields, workflows, issues, KQL, cycles, views, reports, intake, time tracking (server + client skeleton)",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/contract/models.ts

@@ -124,7 +124,6 @@ export const Project = z.object({
   defaultAssignee: z.enum(['unassigned', 'lead']),
   workflowSchemeId: Id.nullable(),
   typeSchemeId: Id.nullable(),
-  fieldSchemeId: Id.nullable(),
   settings: ProjectSettings,
   /** public intake form token (null = intake disabled) */
   intakeToken: z.string().nullable(),
@@ -141,6 +140,14 @@ export const Project = z.object({
 })
 export type Project = z.infer<typeof Project>
 
+/**
+ * The built-in project templates. `software`, `support`, `marketing` and `simple` are the four
+ * team shapes the tracker ships with; `kanban` and `blank` are kept because existing projects were
+ * created from them.
+ */
+export const ProjectTemplateId = z.enum(['software', 'support', 'marketing', 'simple', 'kanban', 'blank'])
+export type ProjectTemplateId = z.infer<typeof ProjectTemplateId>
+
 export const CreateProject = z.object({
   key: ProjectKey,
   name: z.string().min(1).max(120),
@@ -150,8 +157,8 @@ export const CreateProject = z.object({
   leadId: UserId.optional(),
   visibility: ProjectVisibility.default('workspace'),
   defaultAssignee: z.enum(['unassigned', 'lead']).default('unassigned'),
-  /** seed types/workflow from a built-in template */
-  template: z.enum(['software', 'kanban', 'simple', 'blank']).default('software'),
+  /** seed types/workflow/fields from a built-in template */
+  template: ProjectTemplateId.default('software'),
   /** or from a saved project template (overrides `template`) */
   templateId: Id.optional(),
   settings: ProjectSettings.partial().optional(),
@@ -169,7 +176,6 @@ export const UpdateProject = z.object({
   defaultAssignee: z.enum(['unassigned', 'lead']).optional(),
   workflowSchemeId: Id.nullable().optional(),
   typeSchemeId: Id.nullable().optional(),
-  fieldSchemeId: Id.nullable().optional(),
   settings: ProjectSettings.partial().optional(),
 })
 export type UpdateProject = z.infer<typeof UpdateProject>
@@ -186,21 +192,6 @@ export const ProjectMember = z.object({
 })
 export type ProjectMember = z.infer<typeof ProjectMember>
 
-/** Reusable project blueprint (types, workflow, fields, labels, sample views). */
-export const ProjectTemplate = z.object({
-  id: Id,
-  workspaceId: WorkspaceId.nullable(),
-  key: MachineKey,
-  name: z.string().min(1).max(120),
-  description: z.string().max(1000).nullable(),
-  icon: z.string().max(64).nullable(),
-  /** a full ProjectTemplateBody JSON */
-  body: z.record(z.string(), z.unknown()),
-  builtin: z.boolean(),
-  createdAt: Timestamp,
-})
-export type ProjectTemplate = z.infer<typeof ProjectTemplate>
-
 // =====================================================================================
 // work item types & hierarchy
 // =====================================================================================
@@ -209,16 +200,66 @@ export type ProjectTemplate = z.infer<typeof ProjectTemplate>
 export const HierarchyLevel = z.number().int().min(-1).max(2)
 export type HierarchyLevel = z.infer<typeof HierarchyLevel>
 
+/**
+ * The system fields a work item type may lay out, in their default order.
+ *
+ * `pinned` fields are always visible: an issue without a title, a status or a type is not an
+ * issue. The settings editor does not offer the control, and the resolver ignores a stored
+ * instruction that tries to hide one.
+ */
+export const SYSTEM_LAYOUT_FIELDS = [
+  { id: 'title', section: 'main', pinned: true },
+  { id: 'description', section: 'main', pinned: false },
+  { id: 'status', section: 'sidebar', pinned: true },
+  { id: 'type', section: 'sidebar', pinned: true },
+  { id: 'assignees', section: 'sidebar', pinned: false },
+  { id: 'priority', section: 'sidebar', pinned: false },
+  { id: 'labels', section: 'sidebar', pinned: false },
+  { id: 'components', section: 'sidebar', pinned: false },
+  { id: 'versions', section: 'sidebar', pinned: false },
+  { id: 'estimate', section: 'sidebar', pinned: false },
+  { id: 'startDate', section: 'sidebar', pinned: false },
+  { id: 'dueDate', section: 'sidebar', pinned: false },
+  { id: 'cycle', section: 'sidebar', pinned: false },
+  { id: 'milestone', section: 'sidebar', pinned: false },
+  { id: 'parent', section: 'sidebar', pinned: false },
+  { id: 'reporter', section: 'sidebar', pinned: false },
+] as const satisfies ReadonlyArray<{
+  id: string
+  section: 'main' | 'sidebar'
+  pinned: boolean
+}>
+
+export const SystemFieldId = z.enum(SYSTEM_LAYOUT_FIELDS.map((f) => f.id) as [string, ...string[]])
+export type SystemFieldId = (typeof SYSTEM_LAYOUT_FIELDS)[number]['id']
+
+/** System field ids that may never be hidden, whatever a stored layout says. */
+export const PINNED_FIELD_IDS: readonly string[] = SYSTEM_LAYOUT_FIELDS.filter((f) => f.pinned).map(
+  (f) => f.id,
+)
+
+/**
+ * A layout entry's `fieldId` is a *namespaced* name: a system field id (`priority`, `dueDate`) or
+ * `cf.<key>` for a custom field. That is the same string KQL, `ViewDisplay.columns` and workflow
+ * post-functions already use, so one resolver serves all four.
+ */
+export const LayoutFieldId = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(/^(?:[a-zA-Z][a-zA-Z0-9_]*|cf\.[a-z][a-z0-9_]*)$/, 'Expected a system field id or `cf.<key>`')
+export type LayoutFieldId = z.infer<typeof LayoutFieldId>
+
 export const FieldLayoutItem = z.object({
-  /** system field name (`priority`, `dueDate`…) or custom field id */
-  fieldId: z.string().min(1),
+  /** system field id (`priority`, `dueDate`…) or `cf.<key>` for a custom field */
+  fieldId: LayoutFieldId,
   section: z.enum(['main', 'sidebar', 'hidden']).default('sidebar'),
+  /** required on this type, over and above the field definition's own `required` */
   required: z.boolean().default(false),
   hidden: z.boolean().default(false),
   order: z.number().int().default(0),
 })
 export type FieldLayoutItem = z.infer<typeof FieldLayoutItem>
-
 export const WorkItemType = z.object({
   id: Id,
   workspaceId: WorkspaceId,
@@ -377,15 +418,37 @@ export const UpsertFieldDef = z.object({
 })
 export type UpsertFieldDef = z.infer<typeof UpsertFieldDef>
 
-/** Field scheme: which custom fields a project exposes (null = all applicable). */
-export const FieldScheme = z.object({
-  id: Id,
-  workspaceId: WorkspaceId,
-  name: z.string().min(1).max(120),
-  fieldIds: z.array(Id),
-  createdAt: Timestamp,
+/** One field as an interface should render it, system and custom fields alike. */
+export const ResolvedField = z.object({
+  fieldId: LayoutFieldId,
+  /** `system` fields are rendered by a built-in component, `custom` ones by their field type */
+  kind: z.enum(['system', 'custom']),
+  label: z.string().min(1).max(120),
+  section: z.enum(['main', 'sidebar']),
+  order: z.number().int(),
+  required: z.boolean(),
+  pinned: z.boolean(),
+  showInCards: z.boolean(),
+  /** present when `kind` is `custom` — everything needed to render and validate the value */
+  field: FieldDef.nullable(),
+})
+export type ResolvedField = z.infer<typeof ResolvedField>
+
+/**
+ * The fields of one work item type in one project, already ordered and merged.
+ *
+ * An **empty stored layout means the default layout** — everything visible. A field the stored
+ * layout does not name appends to `sidebar` rather than disappearing, so a newly created field
+ * shows up instead of looking broken.
+ */
+export const ResolvedLayout = z.object({
+  typeId: Id,
+  projectId: Id.nullable(),
+  main: z.array(ResolvedField),
+  sidebar: z.array(ResolvedField),
+  hidden: z.array(ResolvedField),
 })
-export type FieldScheme = z.infer<typeof FieldScheme>
+export type ResolvedLayout = z.infer<typeof ResolvedLayout>
 
 // =====================================================================================
 // workflows
@@ -1053,6 +1116,13 @@ export const GroupBy = z.enum([
 ])
 export type GroupBy = z.infer<typeof GroupBy>
 
+/**
+ * A group key that may also name a custom field. `GroupBy` stays as it was so nothing that accepts
+ * only the built-in keys has to change; views and `issues.query` accept this wider one.
+ */
+export const GroupByValue = z.union([GroupBy, z.string().regex(/^cf\.[a-z][a-z0-9_]*$/)])
+export type GroupByValue = z.infer<typeof GroupByValue>
+
 export const OrderBy = z.object({
   /** KQL field name (`priority`, `updated`, `rank`, `cf.severity`…) */
   field: z.string().min(1),
@@ -1071,7 +1141,7 @@ export const BoardColumn = z.object({
 export type BoardColumn = z.infer<typeof BoardColumn>
 
 export const ViewDisplay = z.object({
-  groupBy: GroupBy.default('none'),
+  groupBy: GroupByValue.default('none'),
   subGroupBy: GroupBy.optional(),
   orderBy: z.array(OrderBy).default([{ field: 'rank', dir: 'asc' }]),
   /** visible columns (list/spreadsheet): system field names or `cf.<key>` */
@@ -1084,8 +1154,13 @@ export const ViewDisplay = z.object({
   /** board columns (null → one column per status of the project's workflows) */
   boardColumns: z.array(BoardColumn).nullable().default(null),
   wipLimits: z.record(z.string(), z.number().int().positive()).default({}),
-  /** calendar: which date field positions issues */
-  calendarField: z.enum(['dueDate', 'startDate', 'createdAt']).default('dueDate'),
+  /** calendar: which date field positions issues — a system date field or `cf.<key>` */
+  calendarField: z
+    .union([
+      z.enum(['dueDate', 'startDate', 'createdAt', 'updatedAt', 'resolvedAt']),
+      z.string().regex(/^cf\.[a-z][a-z0-9_]*$/),
+    ])
+    .default('dueDate'),
   /** timeline: show dependency arrows */
   showDependencies: z.boolean().default(true),
   density: z.enum(['compact', 'comfortable']).default('comfortable'),
@@ -1420,3 +1495,52 @@ export const IssueApproval = z.object({
   updatedAt: Timestamp,
 })
 export type IssueApproval = z.infer<typeof IssueApproval>
+
+// =====================================================================================
+// project templates
+// =====================================================================================
+
+/**
+ * Everything a template seeds into a new project. This is the *only* description of a template's
+ * contents: the built-in four are values of this type in code, and a template saved from an
+ * existing project snapshots into the same shape, so one applier serves both.
+ *
+ * Ids inside a body are template-local. Workflows are named by index, types name their workflow by
+ * that index, and layouts name fields by `cf.<key>` — nothing here refers to a database id, which
+ * is what lets a body created in one workspace apply in another.
+ */
+export const ProjectTemplateBody = z.object({
+  version: z.literal(1).default(1),
+  settings: ProjectSettings.partial().optional(),
+  workflows: z
+    .array(z.object({ name: z.string().min(1).max(120), definition: WorkflowDefinition }))
+    .default([]),
+  fields: z.array(UpsertFieldDef).default([]),
+  types: z
+    .array(
+      UpsertWorkItemType.omit({ workflowId: true }).extend({
+        /** index into `workflows`; null → the project's default workflow */
+        workflowIndex: z.number().int().nonnegative().nullable().default(null),
+      }),
+    )
+    .default([]),
+  labels: z
+    .array(z.object({ name: z.string().min(1).max(60), color: Color.nullable().default(null) }))
+    .default([]),
+  views: z.array(UpsertView).default([]),
+})
+export type ProjectTemplateBody = z.infer<typeof ProjectTemplateBody>
+
+/** Reusable project blueprint (types, workflow, fields, labels, sample views). */
+export const ProjectTemplate = z.object({
+  id: Id,
+  workspaceId: WorkspaceId.nullable(),
+  key: MachineKey,
+  name: z.string().min(1).max(120),
+  description: z.string().max(1000).nullable(),
+  icon: z.string().max(64).nullable(),
+  body: ProjectTemplateBody,
+  builtin: z.boolean(),
+  createdAt: Timestamp,
+})
+export type ProjectTemplate = z.infer<typeof ProjectTemplate>

package/src/contract/router.ts

@@ -16,7 +16,6 @@ import {
   Cycle,
   DateOnly,
   FieldDef,
-  FieldScheme,
   HierarchyRules,
   ImportJob,
   ImportSource,
@@ -42,6 +41,7 @@ import {
   RecurringIssue,
   RelationType,
   RelationView,
+  ResolvedLayout,
   RichDoc,
   StatusHistoryEntry,
   StatusInfo,
@@ -173,6 +173,11 @@ export const trackerContract = {
       .route({ method: 'POST', path: '/types/{id}/archive', ...t('types') })
       .input(ws.extend({ id: Id, archived: z.boolean().default(true) }))
       .output(WorkItemType),
+    /** the fields of one type in one project, ordered and merged — what a form should render */
+    layout: baseContract
+      .route({ method: 'GET', path: '/types/{id}/layout', ...t('types') })
+      .input(ws.extend({ id: Id, projectId: Id.nullable().optional() }))
+      .output(ResolvedLayout),
     hierarchyRules: baseContract
       .route({ method: 'GET', path: '/types/hierarchy-rules', ...t('types') })
       .input(ws)
@@ -238,32 +243,6 @@ export const trackerContract = {
       .route({ method: 'DELETE', path: '/fields/{id}', ...t('fields') })
       .input(ws.extend({ id: Id }))
       .output(Ok),
-    schemes: {
-      list: baseContract
-        .route({ method: 'GET', path: '/field-schemes', ...t('fields') })
-        .input(ws)
-        .output(z.array(FieldScheme)),
-      create: baseContract
-        .route({ method: 'POST', path: '/field-schemes', ...t('fields') })
-        .input(ws.extend({ name: z.string().min(1).max(120), fieldIds: z.array(Id) }))
-        .output(FieldScheme),
-      update: baseContract
-        .route({ method: 'PATCH', path: '/field-schemes/{id}', ...t('fields') })
-        .input(
-          ws.extend({
-            id: Id,
-            patch: z.object({
-              name: z.string().min(1).max(120).optional(),
-              fieldIds: z.array(Id).optional(),
-            }),
-          }),
-        )
-        .output(FieldScheme),
-      delete: baseContract
-        .route({ method: 'DELETE', path: '/field-schemes/{id}', ...t('fields') })
-        .input(ws.extend({ id: Id }))
-        .output(Ok),
-    },
   },
 
   // ------------------------------------------------------------------ workflows

package/src/kql/fields.ts

@@ -143,7 +143,11 @@ export function customKqlField(key: string, fieldType: FieldType, label: string)
     name: `cf.${key}`,
     kind,
     label,
-    array: fieldType === 'multiselect' || fieldType === 'multiuser' || fieldType === 'label',
+    array:
+      fieldType === 'multiselect' ||
+      fieldType === 'multiuser' ||
+      fieldType === 'label' ||
+      fieldType === 'relation',
     sortable: kind === 'number' || kind === 'date' || kind === 'datetime' || kind === 'text',
     custom: { key, fieldType },
   }