@kernhq/module-tracker 0.1.0

package/migrations/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1787397066442,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1787397066443,
+      "tag": "0001_rls",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@kernhq/module-tracker",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KernAIO/modules",
+    "directory": "packages/tracker"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "src/client",
+    "docs"
+  ],
+  "exports": {
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "import": "./dist/contract/index.js"
+    },
+    "./kql": {
+      "types": "./dist/kql/index.d.ts",
+      "import": "./dist/kql/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "svelte": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./client/*": {
+      "types": "./src/client/*",
+      "svelte": "./src/client/*",
+      "default": "./src/client/*"
+    },
+    "./migrations": "./migrations"
+  },
+  "dependencies": {
+    "@kernhq/contracts": "^0.1.0",
+    "@kernhq/kernel": "^0.1.0",
+    "@kernhq/sdk": "^0.1.0",
+    "@kernhq/workflow": "^0.1.0",
+    "@orpc/contract": "^1.15.0",
+    "@orpc/server": "^1.15.0",
+    "drizzle-orm": "^0.45.0",
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@kernhq/tsconfig": "^0.1.0",
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.0",
+    "drizzle-kit": "^0.31.0",
+    "pg": "^8.16.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "test:unit": "vitest run --exclude 'src/**/*.int.test.ts'",
+    "db:generate": "drizzle-kit generate"
+  }
+}

package/src/client/api.ts

@@ -0,0 +1,15 @@
+import { createModuleClient, type KernClientOptions } from '@kernhq/sdk'
+import type { ContractRouterClient } from '@orpc/contract'
+import type { TrackerContract } from '../contract/index.js'
+
+/**
+ * Typed oRPC client for `/api/tracker` (see `../contract`).
+ *
+ * The shape is generated from the contract, so every procedure, input and output stays in step with
+ * the server without a second declaration: if the contract changes, callers stop compiling.
+ */
+export type TrackerApi = ContractRouterClient<TrackerContract>
+
+export function createTrackerClient(opts: KernClientOptions): TrackerApi {
+  return createModuleClient<TrackerApi>(opts, 'tracker')
+}

package/src/client/format.ts

@@ -0,0 +1,164 @@
+import type { StatusCategory } from '@kernhq/workflow'
+import type { Priority } from '../contract/models.js'
+
+/**
+ * Presentation rules shared by every tracker surface (list rows, board cards, detail panel).
+ *
+ * Everything here is pure and framework-free so the same rules can be unit-tested and reused by any
+ * host: the Svelte components only turn these values into markup. Colours are design-system tokens
+ * (`--kern-*`), never literal hex, so light mode, dark mode and any future theme all work.
+ * See `app/DESIGN.md` §3.0 for the drawing spec these values implement.
+ */
+
+/** The five status treatments the design draws (DESIGN.md §3.0). */
+export type StatusVisual = 'triage' | 'todo' | 'in_progress' | 'in_review' | 'done' | 'cancelled'
+
+export interface StatusStyle {
+  visual: StatusVisual
+  /** stroke/fill colour for the status glyph */
+  color: string
+  /** chip background for the same status */
+  tint: string
+  /** SVG stroke-dasharray, `null` for a solid ring */
+  dash: string | null
+  /** inner fill path (16×16 viewBox), `null` for an empty ring */
+  fill: string | null
+}
+
+const STYLES: Record<StatusVisual, StatusStyle> = {
+  triage: {
+    visual: 'triage',
+    color: 'var(--kern-ink-280)',
+    tint: 'var(--kern-surface-chip)',
+    dash: '2.2 2',
+    fill: null,
+  },
+  todo: {
+    visual: 'todo',
+    color: 'var(--kern-ink-350)',
+    tint: 'var(--kern-surface-chip)',
+    dash: null,
+    fill: null,
+  },
+  in_progress: {
+    visual: 'in_progress',
+    color: 'var(--kern-accent)',
+    tint: 'var(--kern-accent-tint)',
+    dash: null,
+    fill: 'M8 5.2h2.8v5.6H8z',
+  },
+  in_review: {
+    visual: 'in_review',
+    color: 'var(--kern-purple-status)',
+    tint: 'var(--kern-purple-tint-2)',
+    dash: null,
+    fill: 'M8 5.2h2.8v5.6H5.2V8H8z',
+  },
+  done: {
+    visual: 'done',
+    color: 'var(--kern-success)',
+    tint: 'var(--kern-success-tint-2)',
+    dash: null,
+    fill: 'M5.2 5.2h5.6v5.6H5.2z',
+  },
+  cancelled: {
+    visual: 'cancelled',
+    color: 'var(--kern-ink-330)',
+    tint: 'var(--kern-surface-chip)',
+    dash: null,
+    fill: 'M5.2 5.2h5.6v5.6H5.2z',
+  },
+}
+
+/** Statuses whose id or name marks them as a review step get the purple treatment. */
+const REVIEW = /(^|[-_ ])(review|qa|verify|verification)([-_ ]|$)/i
+
+/**
+ * Pick the drawing for a status. The workflow category decides the shape; a status that reads as a
+ * review step inside `in_progress` gets its own colour, which is what the design shows.
+ */
+export function statusStyle(category: StatusCategory, statusId?: string | null, name?: string | null) {
+  if (category === 'in_progress' && ((statusId && REVIEW.test(statusId)) || (name && REVIEW.test(name)))) {
+    return STYLES.in_review
+  }
+  switch (category) {
+    case 'triage':
+      return STYLES.triage
+    case 'backlog':
+    case 'todo':
+      return STYLES.todo
+    case 'in_progress':
+      return STYLES.in_progress
+    case 'done':
+      return STYLES.done
+    case 'cancelled':
+      return STYLES.cancelled
+    default:
+      return STYLES.todo
+  }
+}
+
+/** Group ordering for "group by status": triage first, finished work last (DESIGN.md §3.2). */
+export const STATUS_CATEGORY_ORDER: Record<StatusCategory, number> = {
+  triage: 0,
+  backlog: 1,
+  todo: 2,
+  in_progress: 3,
+  done: 4,
+  cancelled: 5,
+}
+
+/** Highest priority first, matching the design's group order (Urgent, High, Medium, Low). */
+export const PRIORITY_GROUP_ORDER: Priority[] = ['urgent', 'high', 'medium', 'low', 'none']
+
+/**
+ * The three bars of the priority glyph (DESIGN.md §3.0). `true` = lit.
+ * `none` is drawn as an empty box so the column never collapses.
+ */
+export function priorityBars(priority: Priority): [boolean, boolean, boolean] {
+  switch (priority) {
+    case 'urgent':
+    case 'high':
+      return [true, true, true]
+    case 'medium':
+      return [true, true, false]
+    case 'low':
+      return [true, false, false]
+    default:
+      return [false, false, false]
+  }
+}
+
+/** Geometry of the three bars, shared by the glyph component and any future renderer. */
+export const PRIORITY_BAR_GEOMETRY = [
+  { x: 1.5, y: 9, height: 5.5 },
+  { x: 6.5, y: 5.5, height: 9 },
+  { x: 11.5, y: 2, height: 12.5 },
+] as const
+
+export type DueTone = 'hot' | 'normal'
+
+/** Today and tomorrow (and anything overdue) are "hot" and drawn in danger red (DESIGN.md §3.0). */
+export function dueTone(dueDate: string, today = new Date()): DueTone {
+  const days = daysUntil(dueDate, today)
+  return days <= 1 ? 'hot' : 'normal'
+}
+
+/** Whole days between today (local) and a `YYYY-MM-DD` date; negative when overdue. */
+export function daysUntil(dueDate: string, today = new Date()): number {
+  const [y, m, d] = dueDate.split('-').map(Number)
+  if (!y || !m || !d) return Number.POSITIVE_INFINITY
+  const due = Date.UTC(y, m - 1, d)
+  const start = Date.UTC(today.getFullYear(), today.getMonth(), today.getDate())
+  return Math.round((due - start) / 86_400_000)
+}
+
+/** Seconds of logged time as the board footer shows it ("0h", "3h", "1d 2h"). */
+export function formatDuration(seconds: number): string {
+  if (seconds <= 0) return '0h'
+  const hours = Math.round(seconds / 3600)
+  if (hours < 24) return `${hours}h`
+  const days = Math.floor(hours / 24)
+  const rest = hours % 24
+  return rest ? `${days}d ${rest}h` : `${days}d`
+}

package/src/client/group.ts

@@ -0,0 +1,150 @@
+import type { StatusCategory } from '@kernhq/workflow'
+import type { GroupBy, Issue, Priority } from '../contract/models.js'
+import { PRIORITY_GROUP_ORDER, STATUS_CATEGORY_ORDER } from './format.js'
+import { byRank } from './rank.js'
+
+/**
+ * Turning a flat list of issues into the grouped list and board the design draws.
+ *
+ * Kept separate from the components because the rules have edges worth testing: multi-valued fields
+ * (assignees, labels) put an issue in every group it belongs to, unassigned work still needs a
+ * group, empty groups are hidden, and the group order is prescribed per grouping (DESIGN.md 3.2).
+ */
+
+/** `null` is the "no value" group: Unassigned, No label, No cycle and so on. */
+export type GroupKey = string | null
+
+export interface IssueGroup<T> {
+  key: GroupKey
+  items: T[]
+  /** sum of estimates, `null` when nothing in the group is estimated */
+  estimate: number | null
+}
+
+/** Everything grouping needs to know that does not live on the issue itself. */
+export interface GroupContext {
+  /** display order of a status inside the board and list (workflow order) */
+  statusOrder(statusId: string): number
+  statusCategory(statusId: string): StatusCategory
+  /** display order for the remaining reference fields; unknown ids sort last */
+  order?(groupBy: GroupBy, key: string): number
+}
+
+type Groupable = Pick<
+  Issue,
+  | 'statusId'
+  | 'statusCategory'
+  | 'priority'
+  | 'assigneeIds'
+  | 'labelIds'
+  | 'componentIds'
+  | 'versionIds'
+  | 'typeId'
+  | 'cycleId'
+  | 'milestoneId'
+  | 'projectId'
+  | 'parentId'
+  | 'dueDate'
+  | 'createdAt'
+  | 'estimate'
+  | 'rank'
+>
+
+/** Every group an issue belongs to under `groupBy`. Multi-valued fields yield more than one. */
+export function groupKeysOf(issue: Groupable, groupBy: GroupBy): GroupKey[] {
+  switch (groupBy) {
+    case 'status':
+      return [issue.statusId]
+    case 'statusCategory':
+      return [issue.statusCategory]
+    case 'priority':
+      return [issue.priority]
+    case 'type':
+      return [issue.typeId]
+    case 'project':
+      return [issue.projectId]
+    case 'assignee':
+      return issue.assigneeIds.length ? [...issue.assigneeIds] : [null]
+    case 'label':
+      return issue.labelIds.length ? [...issue.labelIds] : [null]
+    case 'component':
+      return issue.componentIds.length ? [...issue.componentIds] : [null]
+    case 'version':
+      return issue.versionIds.length ? [...issue.versionIds] : [null]
+    case 'cycle':
+      return [issue.cycleId]
+    case 'milestone':
+      return [issue.milestoneId]
+    case 'parent':
+      return [issue.parentId]
+    case 'dueDate':
+      return [issue.dueDate]
+    case 'createdAt':
+      return [issue.createdAt.slice(0, 10)]
+    default:
+      return [null]
+  }
+}
+
+/** Sort weight for a group heading. Lower comes first; the "no value" group always goes last. */
+export function groupOrder(key: GroupKey, groupBy: GroupBy, ctx: GroupContext): number {
+  if (key === null) return Number.MAX_SAFE_INTEGER
+  switch (groupBy) {
+    case 'status':
+      return STATUS_CATEGORY_ORDER[ctx.statusCategory(key)] * 1000 + ctx.statusOrder(key)
+    case 'statusCategory':
+      return STATUS_CATEGORY_ORDER[key as StatusCategory] ?? 900
+    case 'priority': {
+      const i = PRIORITY_GROUP_ORDER.indexOf(key as Priority)
+      return i < 0 ? 900 : i
+    }
+    default:
+      return ctx.order?.(groupBy, key) ?? 0
+  }
+}
+
+/**
+ * Group and order issues for the list and the board.
+ *
+ * Groups with no rows are dropped, because the design never shows an empty heading. The exception is
+ * `alwaysShow`, which is how a board keeps an empty column you can still drop a card into.
+ */
+export function groupIssues<T extends Groupable>(
+  issues: readonly T[],
+  groupBy: GroupBy,
+  ctx: GroupContext,
+  opts: { alwaysShow?: readonly GroupKey[]; compare?: (a: T, b: T) => number } = {},
+): Array<IssueGroup<T>> {
+  const compare = opts.compare ?? byRank
+  const buckets = new Map<string, IssueGroup<T>>()
+  const keyId = (k: GroupKey) => (k === null ? ' none' : k)
+
+  for (const key of opts.alwaysShow ?? []) {
+    buckets.set(keyId(key), { key, items: [], estimate: null })
+  }
+  for (const issue of issues) {
+    for (const key of groupKeysOf(issue, groupBy)) {
+      const id = keyId(key)
+      let bucket = buckets.get(id)
+      if (!bucket) {
+        bucket = { key, items: [], estimate: null }
+        buckets.set(id, bucket)
+      }
+      bucket.items.push(issue)
+    }
+  }
+
+  const always = new Set((opts.alwaysShow ?? []).map(keyId))
+  return [...buckets.values()]
+    .filter((g) => g.items.length > 0 || always.has(keyId(g.key)))
+    .map((g) => {
+      g.items.sort(compare)
+      const estimates = g.items.map((i) => i.estimate).filter((e): e is number => typeof e === 'number')
+      g.estimate = estimates.length ? estimates.reduce((a, b) => a + b, 0) : null
+      return g
+    })
+    .sort((a, b) => {
+      const d = groupOrder(a.key, groupBy, ctx) - groupOrder(b.key, groupBy, ctx)
+      return d !== 0 ? d : String(a.key ?? '').localeCompare(String(b.key ?? ''))
+    })
+}

package/src/client/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Tracker client entry.
+ *
+ * The pieces a host application needs to talk to the tracker and to render it the way `DESIGN.md`
+ * describes, with no framework in them: a typed API client, the presentation rules for statuses,
+ * priorities and due dates, grouping for the list and the board, fractional ranks for drag and drop,
+ * and a KQL reader for the query box.
+ *
+ * The Svelte views themselves live in the host app (`repos/app/src/lib/modules/tracker`) for now:
+ * the shell renders module pages as real SvelteKit routes rather than through `ClientModule.routes`,
+ * so shipping components from here would have nowhere to be mounted.
+ */
+
+export { createTrackerClient, type TrackerApi } from './api.js'
+export {
+  type DueTone,
+  daysUntil,
+  dueTone,
+  formatDuration,
+  PRIORITY_BAR_GEOMETRY,
+  PRIORITY_GROUP_ORDER,
+  priorityBars,
+  STATUS_CATEGORY_ORDER,
+  type StatusStyle,
+  type StatusVisual,
+  statusStyle,
+} from './format.js'
+export {
+  type GroupContext,
+  type GroupKey,
+  groupIssues,
+  groupKeysOf,
+  groupOrder,
+  type IssueGroup,
+} from './group.js'
+export {
+  customKqlField,
+  type KqlComparison,
+  type KqlExpr,
+  type KqlField,
+  type KqlOp,
+  type KqlOrder,
+  type KqlQuery,
+  type KqlValue,
+  operatorsFor,
+  type ParsedKql,
+  type ParseOptions,
+  parseKql,
+  type Span,
+  SYSTEM_FIELDS,
+} from './kql.js'
+export {
+  byRank,
+  initialRank,
+  isValidRank,
+  rankBetween,
+  rankForIndex,
+  rankSequence,
+} from './rank.js'
+export type * from './types.js'