@kernhq/module-hr 0.1.0

package/migrations/meta/_journal.json

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

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@kernhq/module-hr",
+  "version": "0.1.0",
+  "description": "Kern HR module: people, offices, org chart, calendars",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "files": [
+    "dist",
+    "migrations",
+    "src/client",
+    "src/contract"
+  ],
+  "exports": {
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "import": "./dist/contract/index.js",
+      "default": "./dist/contract/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "svelte": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./migrations": "./migrations",
+    "./client/*": {
+      "types": "./src/client/*",
+      "svelte": "./src/client/*",
+      "default": "./src/client/*"
+    }
+  },
+  "dependencies": {
+    "@kernhq/contracts": "^0.5.0",
+    "@kernhq/kernel": "^0.6.0",
+    "@kernhq/sdk": "^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",
+    "drizzle-kit": "^0.31.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "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",
+    "test": "vitest run",
+    "db:generate": "drizzle-kit generate"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,62 @@
+import { createModuleClient, type KernClientOptions } from '@kernhq/sdk'
+import type { ContractRouterClient } from '@orpc/contract'
+import type { HrContract } from '../contract/index.js'
+
+/**
+ * The client half.
+ *
+ * Published as **source**, not compiled: the consumer builds the TypeScript and Svelte with its own
+ * toolchain, which is what lets `$state` in a module store stay reactive inside the app. Two
+ * consequences worth knowing before you edit anything here — nothing in this package compiles it,
+ * so `pnpm build` passes over a syntax error and only the app finds it; and `files` in package.json
+ * must cover every directory this entry reaches, contract source included.
+ *
+ * What lives here: the typed API client, and any logic that is about this module but not about a
+ * screen (formatting, grouping, parsing). What does not: the `defineClientModule` manifest and the
+ * Svelte components, which live in the app so their labels can go through its message catalogue.
+ * `pnpm new-module` generates both halves.
+ */
+export type HrApi = ContractRouterClient<HrContract>
+
+export function createHrClient(opts: KernClientOptions): HrApi {
+  return createModuleClient<HrApi>(opts, 'hr')
+}
+
+export {
+  type Calendar,
+  type CalendarDay,
+  type CostCenter,
+  type CustomFieldDef,
+  type Employment,
+  HR_PERMISSIONS,
+  hrCapabilities,
+  hrPermissions,
+  type IsoDate,
+  type LegalEntity,
+  MODULE_ID,
+  type Office,
+  type OfficeAssignment,
+  type OrgUnit,
+  type Person,
+  type PersonDocument,
+  type PersonResolution,
+  type PersonStatus,
+  type Position,
+  type ResolvedCalendarDay,
+  type WorkingWeek,
+} from '../contract/index.js'
+
+/**
+ * The capability ids, so a client contribution gates on a constant rather than a retyped string.
+ *
+ * Named unqualified — `capability: HR_CAPABILITIES.offices` gives `'offices'`, not `'hr.offices'` —
+ * because from inside a module there is only one namespace. The shell adds this module's id when it
+ * builds the workspace's set, which is where several modules' capabilities meet.
+ */
+export const HR_CAPABILITIES = {
+  core: 'core',
+  offices: 'offices',
+  legalEntities: 'legal_entities',
+  calendars: 'calendars',
+  documents: 'documents',
+} as const

package/src/contract/capabilities.ts

@@ -0,0 +1,117 @@
+import { defineCapabilities } from '@kernhq/contracts'
+
+/**
+ * How much HR this workspace has.
+ *
+ * HR is the module capabilities were built for. One company wants a staff directory and nothing
+ * else; a second wants leave, balances and approvals; a third runs shift rosters and clocks people
+ * in at a factory gate. Those are three products under one name, and the alternatives to this
+ * registry are a code fork per customer or a navigation rail full of features nobody uses.
+ *
+ * **A capability is declared here only once something is behind it.** A switch that changes nothing
+ * is worse than a missing switch: it teaches an administrator that the switchboard does not mean
+ * anything. So this list grows with the module rather than describing where the module is going —
+ * `leave`, `attendance`, `overtime`, `rosters`, `periods` and `payroll_export` arrive with the
+ * phases that implement them.
+ *
+ * Two rules that decide whether something belongs here at all:
+ *
+ * - **Not a permission.** "May Ayşe approve leave" is a permission — true for her, false for someone
+ *   else, in the same workspace. "Does this company do leave" is a capability: one answer for
+ *   everyone, the owner included.
+ * - **Reversible without a migration.** Switching one off writes a boolean into module settings;
+ *   the rows stay exactly where they are and switching it back on restores them. Anything that would
+ *   need data thrown away is not a capability, however much it looks like one.
+ */
+export const hrCapabilities = defineCapabilities([
+  {
+    id: 'core',
+    label: 'People',
+    description: 'The staff directory, employment records and reporting lines',
+    required: true,
+    level: 1,
+  },
+  {
+    id: 'offices',
+    label: 'Offices',
+    description: 'More than one place of work, each with its own country, timezone and holidays',
+    dependsOn: ['core'],
+    // Off by default, and invisible when off — but the *concept* is never absent. A workspace always
+    // has exactly one office, built from its country when HR is enabled, and everybody is assigned
+    // to it. Switching this on reveals the list and the assignment control; it does not migrate
+    // anything, because the shape was there from the first day. A workspace that only ever has one
+    // office never meets the word.
+    defaultEnabled: false,
+    level: 2,
+  },
+  {
+    id: 'legal_entities',
+    label: 'Legal entities',
+    description: 'Several employing companies, for a group operating across borders',
+    // Depends on offices rather than core: a single-site company has one employer by definition, and
+    // the question only becomes real once there is more than one place of work.
+    dependsOn: ['offices'],
+    defaultEnabled: false,
+    level: 3,
+  },
+  {
+    id: 'calendars',
+    label: 'Holiday calendars',
+    description: 'Public holidays, company closures and the working week',
+    dependsOn: ['core'],
+    // On by default. Every company has holidays, and a directory that does not know when people are
+    // off is answering a question nobody asked.
+    defaultEnabled: true,
+    level: 1,
+  },
+  {
+    id: 'documents',
+    label: 'Employee documents',
+    description: 'Contracts, identity documents and certificates against a person',
+    dependsOn: ['core'],
+    defaultEnabled: false,
+    level: 2,
+  },
+])
+
+export type HrCapabilityId = (typeof hrCapabilities)[number]['id']
+
+/**
+ * Which procedures sit behind which capability.
+ *
+ * Declared as data because a missing `requiresCapability` is invisible: the procedure compiles,
+ * every other test passes, and the only symptom is a workspace calling a feature it switched off.
+ * `module.test.ts` reads this and fails when a procedure named here is not carrying the middleware.
+ *
+ * A procedure absent from this map belongs to the module as a whole and is reachable whenever HR is
+ * on — which for `core` is always, because it is `required`.
+ */
+export const hrCapabilityProcedures: Record<string, readonly string[]> = {
+  offices: [
+    'offices.list',
+    'offices.get',
+    'offices.create',
+    'offices.update',
+    'offices.archive',
+    'offices.setDefault',
+    'offices.assign',
+    'offices.unassign',
+    'offices.people',
+  ],
+  legal_entities: ['entities.list', 'entities.get', 'entities.create', 'entities.update', 'entities.archive'],
+  calendars: [
+    'calendars.list',
+    'calendars.get',
+    'calendars.create',
+    'calendars.update',
+    'calendars.archive',
+    'calendars.days.list',
+    'calendars.days.add',
+    'calendars.days.update',
+    'calendars.days.remove',
+    'calendars.pack.preview',
+    'calendars.pack.apply',
+    'calendars.workingDays',
+  ],
+  documents: ['documents.list', 'documents.attach', 'documents.remove'],
+}

package/src/contract/events.ts

@@ -0,0 +1,84 @@
+import { defineEvent, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+
+/**
+ * `hr.<entity>.<action>`. Anything that emits one declares it here.
+ *
+ * These are what the rest of the product reacts to. Chat wants to know when somebody joins so it can
+ * add them to a channel; a future calendar wants office holidays; payroll wants an employment
+ * change. The payloads carry ids rather than rows on purpose — a subscriber that needs the record
+ * asks for it with its own principal, so an event cannot become a way to read data past a permission
+ * check.
+ */
+export const hrEvents = {
+  personCreated: defineEvent(
+    'hr.person.created',
+    z.object({ personId: z.uuid(), workspaceId: WorkspaceId, userId: z.uuid().nullable() }),
+  ),
+  personUpdated: defineEvent(
+    'hr.person.updated',
+    z.object({ personId: z.uuid(), workspaceId: WorkspaceId, fields: z.array(z.string()) }),
+  ),
+  /**
+   * Status moved — onboarding to active, active to terminated.
+   *
+   * Separate from `personUpdated` because the things that care about a lifecycle change (revoking
+   * access, closing a leave balance, ending a payroll line) do not want to filter every profile
+   * edit to find it.
+   */
+  personStatusChanged: defineEvent(
+    'hr.person.status_changed',
+    z.object({
+      personId: z.uuid(),
+      workspaceId: WorkspaceId,
+      from: z.string(),
+      to: z.string(),
+      on: z.iso.date(),
+    }),
+  ),
+  employmentChanged: defineEvent(
+    'hr.employment.changed',
+    z.object({
+      personId: z.uuid(),
+      workspaceId: WorkspaceId,
+      employmentId: z.uuid(),
+      effectiveFrom: z.iso.date(),
+    }),
+  ),
+  /**
+   * Somebody's office changed, or their primary did.
+   *
+   * Worth its own event because the primary office decides holidays, timezone and policy: anything
+   * holding a derived answer for this person has to recompute, and this is how it finds out.
+   */
+  officeAssignmentChanged: defineEvent(
+    'hr.office_assignment.changed',
+    z.object({
+      personId: z.uuid(),
+      workspaceId: WorkspaceId,
+      officeId: z.uuid(),
+      isPrimary: z.boolean(),
+      effectiveFrom: z.iso.date(),
+    }),
+  ),
+  officeCreated: defineEvent(
+    'hr.office.created',
+    z.object({ officeId: z.uuid(), workspaceId: WorkspaceId, country: z.string() }),
+  ),
+  /**
+   * A calendar's days changed — a holiday added, a pack applied.
+   *
+   * Everything derived from a calendar (working days, leave day counts, later the attendance day
+   * sheet) is stale from here. The payload names the date range touched so a consumer can recompute
+   * that window rather than everything.
+   */
+  calendarChanged: defineEvent(
+    'hr.calendar.changed',
+    z.object({
+      calendarId: z.uuid(),
+      workspaceId: WorkspaceId,
+      from: z.iso.date().nullable(),
+      to: z.iso.date().nullable(),
+    }),
+  ),
+}

package/src/contract/index.ts

@@ -0,0 +1,14 @@
+/**
+ * What HR offers, as data.
+ *
+ * Imported by **both** halves — the server implements it, the client calls it — so nothing here may
+ * touch Node. The contract is the only thing that crosses that line, which is why a procedure that
+ * exists here and not in the router is a lie that compiles. `module.test.ts` checks exactly that,
+ * and also that every procedure listed in `hrCapabilityProcedures` carries its capability guard.
+ */
+export * from './capabilities.js'
+export * from './events.js'
+export * from './models.js'
+export * from './permissions.js'
+export * from './router.js'
+export * from './settings.js'