@kernhq/module-inventory 0.1.2 → 0.2.0

package/src/server/migrations.test.ts

@@ -0,0 +1,138 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import pg from 'pg'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { TENANT_TABLES } from './schema.js'
+
+/**
+ * The migration folder, applied to a database created from nothing — and then applied again.
+ *
+ * The integration suite already proves the folder *applies*, because `kernel.start()` runs it. It
+ * does not prove the folder is **replayable**, and that is the property that took `core` down: the
+ * kernel migrates every module at boot, so one migration that throws does not degrade its own
+ * feature — `core` hosts five modules and never binds its port. A regenerated
+ * `migrations/meta/_journal.json` is enough to cause a replay, because every entry gets a `when`
+ * newer than the rows already in `mod_inventory.__migrations`.
+ *
+ * Three things here are deliberate, and each of them is a way this test could have been vacuously
+ * green instead:
+ *
+ * 1. **A scratch database, created here.** Running against a database somebody has already migrated
+ *    proves nothing — it is the same shape of mistake as asserting that `migrateModule` succeeds
+ *    twice against a schema that already exists.
+ * 2. **Every statement is executed separately and every failure is collected**, rather than throwing
+ *    on the first. Guarding one class of statement and re-running tells you only about the next one;
+ *    collecting them says how much is actually unguarded. In `module-hr` that difference was 203
+ *    statements hiding behind the policies somebody had just fixed.
+ * 3. **Policies are asserted as `(tablename, policyname)` pairs, not as a count per table.** "One
+ *    policy per table" is the wrong invariant — a table may legitimately carry several — and a
+ *    duplicate pair is exactly what a replay produces.
+ */
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const MIGRATIONS = join(HERE, '../../migrations')
+
+const BASE_URL = process.env.DATABASE_URL ?? 'postgres://kern:kern@localhost:5432/kern'
+const DB_NAME = `kern_inventory_replay_${Date.now().toString(36)}`
+
+let admin: pg.Client
+let db: pg.Client
+
+/** The folder in the order the kernel applies it — by filename, which is why they are numbered. */
+function migrationFiles(): string[] {
+  return readdirSync(MIGRATIONS)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+}
+
+/**
+ * Apply one file statement by statement, returning every failure rather than the first.
+ *
+ * `--> statement-breakpoint` is drizzle's separator. Splitting on it is also why nothing in this
+ * folder may use a dollar-quoted body: a breakpoint inside `do $$ … end $$` cuts the function in
+ * half, and the error is `unterminated dollar-quoted string`, which does not sound like what it is.
+ */
+async function apply(file: string): Promise<Array<{ statement: string; error: string }>> {
+  const sql = readFileSync(join(MIGRATIONS, file), 'utf8')
+  const failures: Array<{ statement: string; error: string }> = []
+  for (const raw of sql.split('--> statement-breakpoint')) {
+    const statement = raw.trim()
+    if (!statement || statement.split('\n').every((l) => l.trim().startsWith('--'))) continue
+    try {
+      await db.query(statement)
+    } catch (err) {
+      failures.push({
+        statement: statement.slice(0, 120).replace(/\s+/g, ' '),
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+  return failures
+}
+
+beforeAll(async () => {
+  admin = new pg.Client({ connectionString: BASE_URL })
+  await admin.connect()
+  await admin.query(`create database "${DB_NAME}"`)
+  const url = new URL(BASE_URL)
+  url.pathname = `/${DB_NAME}`
+  db = new pg.Client({ connectionString: url.toString() })
+  await db.connect()
+}, 120_000)
+
+afterAll(async () => {
+  await db?.end().catch(() => undefined)
+  await admin?.query(`drop database if exists "${DB_NAME}" with (force)`).catch(() => undefined)
+  await admin?.end().catch(() => undefined)
+})
+
+describe('the migration folder', () => {
+  it('applies to a database created from nothing', async () => {
+    for (const file of migrationFiles()) {
+      expect(await apply(file), `${file}, first pass`).toEqual([])
+    }
+  })
+
+  it('applies a second time, because a replay must not take down the host service', async () => {
+    for (const file of migrationFiles()) {
+      expect(await apply(file), `${file}, replay`).toEqual([])
+    }
+  })
+
+  it('leaves exactly one of every policy after the replay', async () => {
+    const { rows } = await db.query<{ tablename: string; policyname: string }>(
+      `select tablename, policyname from pg_policies where schemaname = 'mod_inventory'`,
+    )
+    const seen = rows.map((r) => `${r.tablename}.${r.policyname}`)
+    expect([...new Set(seen)].sort(), 'a duplicate pair is what a replay produces').toEqual(seen.sort())
+    // And the policies are the ones the module declares it has.
+    for (const table of TENANT_TABLES)
+      expect(seen, `mod_inventory.${table} has its policy`).toContain(`${table}.${table}_ws_isolation`)
+  })
+
+  it('forces row-level security on every table that carries a policy', async () => {
+    // Restricted to tables that have one: a module may legitimately keep an unsecured table, and
+    // asserting over every table in the schema would fail on drizzle's own `__migrations`.
+    const { rows } = await db.query<{ relname: string; forced: boolean }>(
+      `select c.relname, c.relforcerowsecurity as forced
+         from pg_class c
+         join pg_namespace n on n.oid = c.relnamespace
+        where n.nspname = 'mod_inventory'
+          and c.relkind = 'r'
+          and exists (select 1 from pg_policies p
+                       where p.schemaname = 'mod_inventory' and p.tablename = c.relname)`,
+    )
+    expect(rows.length, 'no policies found at all — the RLS migration did not run').toBeGreaterThan(0)
+    for (const row of rows) expect(row.forced, `mod_inventory.${row.relname} forces RLS`).toBe(true)
+  })
+
+  it('keeps the exclusion constraint that makes two open custody periods impossible', async () => {
+    const { rows } = await db.query<{ n: string }>(
+      `select count(*) as n from pg_constraint where conname = 'inventory_custody_no_overlap'`,
+    )
+    // Exactly one: `add constraint` is not idempotent on its own, so a replay without the
+    // preceding `drop constraint if exists` would either throw or leave two.
+    expect(Number(rows[0]?.n)).toBe(1)
+  })
+})

package/src/server/router.ts

@@ -0,0 +1,118 @@
+import type { WorkspaceId } from '@kernhq/contracts'
+import {
+  defineModule,
+  defineServerModule,
+  type Kernel,
+  packageVersion,
+  type RequestContext,
+  requires,
+  type Tx,
+  workspaceScoped,
+} from '@kernhq/kernel'
+import { implement } from '@orpc/server'
+import { inventoryContract, inventoryEvents, MODULE_ID } from '../contract/index.js'
+import { toAsset, type Written } from './services/assets.js'
+import { inventoryServices } from './services/index.js'
+
+/**
+ * oRPC router for `/api/inventory`.
+ *
+ * Deliberately thin: it opens the workspace-bound transaction and hands straight over to a service,
+ * which is where the logic lives. Kept apart from `index.ts` so `module.test.ts` can walk it as data
+ * without booting a kernel.
+ *
+ * Two middlewares on every procedure, and the test fails if either is missing: `workspaceScoped`
+ * (a real membership, and the module switched on for that workspace) and `requires` (the permission
+ * this particular call needs). A capability adds a third, between them.
+ */
+export { defineModule, defineServerModule, packageVersion }
+
+const os = implement(inventoryContract).$context<RequestContext>()
+
+export function inventoryRouter(kernel: Kernel) {
+  const svc = inventoryServices(kernel)
+  const scoped = os.use(workspaceScoped(MODULE_ID))
+
+  /**
+   * Everything a write announces, once the transaction that wrote it has actually committed.
+   *
+   * Three things, and all three are after the commit on purpose: the core activity feed's copy of
+   * the history row, the event for whatever reacts later, and the realtime change that redraws a
+   * screen somebody is looking at now. A mutation that skips them leaves the product believing the
+   * old answer; a mutation that fires them *inside* the transaction tells the rest of the instance
+   * about a row a rollback then took away, which is worse — it cannot be retracted.
+   */
+  const announce = async (
+    workspaceId: WorkspaceId,
+    written: Written,
+    event: (typeof inventoryEvents)[keyof typeof inventoryEvents],
+    op: 'created' | 'updated' | 'deleted',
+    actorId: string | null,
+  ) => {
+    const assetId = written.row.id
+    if (written.activity) await svc.notify.activity(written.activity)
+    await kernel.emit(event, { assetId, workspaceId }, { workspaceId, actorId: actorId ?? undefined })
+    await svc.notify.change(workspaceId, 'asset', assetId, op)
+  }
+
+  /** Every handler is this: a workspace-bound transaction, tagged with who is asking, and a service. */
+  const run = <T>(context: RequestContext, workspaceId: string, fn: (tx: Tx) => Promise<T>): Promise<T> =>
+    kernel.database.withWorkspace(workspaceId, fn, { userId: context.principal.userId })
+
+  return os.router({
+    assets: {
+      list: scoped.assets.list
+        .use(requires('inventory.asset.view'))
+        .handler(({ input, context }) => run(context, input.workspaceId, (tx) => svc.assets.list(tx, input))),
+
+      get: scoped.assets.get
+        .use(requires('inventory.asset.view'))
+        .handler(({ input, context }) =>
+          run(context, input.workspaceId, async (tx) =>
+            toAsset(await svc.assets.get(tx, input.workspaceId, input.assetId)),
+          ),
+        ),
+
+      create: scoped.assets.create
+        .use(requires('inventory.asset.manage'))
+        .handler(async ({ input, context }) => {
+          const actorId = context.principal.userId
+          // Module settings are read *before* the transaction opens. They come from core over the
+          // broker, and awaiting that inside the transaction holds a pooled connection and the
+          // counter row lock across a network call to another service.
+          const format = await svc.assets.codeFormat(input.workspaceId)
+          const written = await run(context, input.workspaceId, (tx) =>
+            svc.assets.create(tx, input.workspaceId, actorId, input, format),
+          )
+          await announce(input.workspaceId, written, inventoryEvents.assetCreated, 'created', actorId)
+          return toAsset(written.row)
+        }),
+
+      update: scoped.assets.update
+        .use(requires('inventory.asset.manage'))
+        .handler(async ({ input, context }) => {
+          const actorId = context.principal.userId
+          const written = await run(context, input.workspaceId, (tx) =>
+            svc.assets.update(tx, input.workspaceId, actorId, input.assetId, input),
+          )
+          await announce(input.workspaceId, written, inventoryEvents.assetUpdated, 'updated', actorId)
+          return toAsset(written.row)
+        }),
+
+      archive: scoped.assets.archive
+        .use(requires('inventory.asset.manage'))
+        .handler(async ({ input, context }) => {
+          const actorId = context.principal.userId
+          const written = await run(context, input.workspaceId, (tx) =>
+            svc.assets.archive(tx, input.workspaceId, actorId, input.assetId, input.archived),
+          )
+          // This procedure is the restore path too, and it used to announce `archived` either way —
+          // telling every subscriber that a restored item had just been retired, while the module's
+          // own history row beside it said `restored`.
+          const event = input.archived ? inventoryEvents.assetArchived : inventoryEvents.assetRestored
+          await announce(input.workspaceId, written, event, 'updated', actorId)
+          return toAsset(written.row)
+        }),
+    },
+  })
+}

package/src/server/schema.ts

@@ -7,7 +7,7 @@ import {
   index,
   integer,
   jsonb,
-  pgEnum,
+  primaryKey,
   text,
   timestamp,
   uniqueIndex,
@@ -33,20 +33,23 @@ const ts = (name: string) => timestamp(name, { withTimezone: true, mode: 'date'
 const created = () => ts('created_at').notNull().defaultNow()
 const updated = () => ts('updated_at').notNull().defaultNow()
 
-/**
- * Asset lifecycle. Stored rather than derived because every list filter asks for it; every
- * transition is written inside the same transaction as the row it derives from.
- */
-export const assetStatus = pgEnum('asset_status', ['in_stock', 'assigned', 'under_repair', 'retired'])
-
 export const counters = schema.table(
   'counters',
   /** Per-workspace sequence sources (`asset_code`). Narrow on purpose: one row per key. */
   {
-    workspaceId: ws().primaryKey(),
-    key: text('key').primaryKey(),
+    workspaceId: ws(),
+    key: text('key').notNull(),
     value: integer('value').notNull(),
   },
+  /**
+   * Composite, declared here rather than as two `.primaryKey()` columns.
+   *
+   * Column-level `.primaryKey()` twice reads like a compound key and is not one: drizzle emits
+   * `PRIMARY KEY` on both columns and Postgres refuses the table outright — "multiple primary keys
+   * for table are not allowed", SQLSTATE 42P16. The module's migration is the first thing the
+   * kernel runs, so the failure is not a broken table but a service that will not boot.
+   */
+  (t) => [primaryKey({ columns: [t.workspaceId, t.key] })],
 )
 
 export const categories = schema.table(
@@ -74,7 +77,10 @@ export const assets = schema.table(
     name: text('name').notNull(),
     description: text('description').notNull().default(''),
     categoryId: uuid('category_id'),
-    status: assetStatus('status').notNull().default('in_stock'),
+    /** `AssetStatus` in the contract. Text, not a pg enum: every other Kern module stores a
+     * status this way, and an enum named `asset_status` in `public` is a type this module
+     * leaves behind when it is removed. */
+    status: text('status').notNull().default('in_stock'),
     /** Denormalized from `custody_periods`, which stays authoritative for history. */
     custodianUserId: uuid('custodian_user_id'),
     custodySince: ts('custody_since'),
@@ -86,6 +92,8 @@ export const assets = schema.table(
     currency: char('currency', { length: 3 }),
     warrantyUntil: date('warranty_until'),
     photoFileId: uuid('photo_file_id'),
+    /** Values for this workspace's own `field_defs`, keyed by their `key`. */
+    custom: jsonb('custom').$type<Record<string, unknown>>().notNull().default({}),
     createdAt: created(),
     updatedAt: updated(),
     archivedAt: ts('archived_at'),
@@ -95,6 +103,10 @@ export const assets = schema.table(
     index('inventory_assets_ws_created_idx').on(t.workspaceId, t.createdAt),
     index('inventory_assets_ws_status_idx').on(t.workspaceId, t.status),
     index('inventory_assets_ws_category_idx').on(t.workspaceId, t.categoryId),
+    // "What is Ada holding?" — asked by the person, by the offboarding hook, and by a widget.
+    index('inventory_assets_ws_custodian_idx')
+      .on(t.workspaceId, t.custodianUserId)
+      .where(sql`custodian_user_id is not null`),
     // The "what leaves warranty this month" scan, before a job makes it a widget's cheap query.
     index('inventory_assets_ws_warranty_idx')
       .on(t.workspaceId, t.warrantyUntil)
@@ -218,6 +230,11 @@ export const attachments = schema.table(
 
 /** Every tenant table, so the RLS migration can be checked against one list rather than memory. */
 export const TENANT_TABLES = [
+  // `counters` is a tenant table like any other: it carries `workspace_id`, so one workspace's
+  // asset-code sequence is readable to another without a policy. It was left out of this list —
+  // and therefore out of `0001_rls.sql` — because it holds no asset data, which is not the rule
+  // the file states at the top. Tracker's structurally identical `issue_counters` is covered.
+  'counters',
   'categories',
   'assets',
   'field_defs',