@kernhq/module-inventory 0.1.1 → 0.2.0

package/src/contract/router.ts

@@ -0,0 +1,46 @@
+import { baseContract, PageInput, page } from '@kernhq/contracts'
+import { z } from 'zod'
+import { Asset, AssetCreateInput, AssetPatchInput, AssetSort, AssetStatus, ws } from './models.js'
+
+const t = ['inventory'] as const
+
+export const inventoryContract = {
+  assets: {
+    list: baseContract
+      .route({ method: 'GET', path: '/assets', tags: t })
+      .input(
+        ws.extend({
+          ...PageInput.shape,
+          q: z.string().max(200).optional(),
+          categoryId: z.uuid().optional(),
+          status: AssetStatus.optional(),
+          custodianUserId: z.uuid().optional(),
+          /**
+           * Archived rows are excluded unless asked for. The page used to filter them in the
+           * browser, which is wrong the moment there is more than one page of them: the first
+           * twenty rows come back, half are dropped, and the list looks short rather than paged.
+           */
+          archived: z.boolean().default(false),
+          sort: AssetSort.default('recent'),
+        }),
+      )
+      .output(page(Asset)),
+    get: baseContract
+      .route({ method: 'GET', path: '/assets/{assetId}', tags: t })
+      .input(ws.extend({ assetId: z.uuid() }))
+      .output(Asset),
+    create: baseContract
+      .route({ method: 'POST', path: '/assets', tags: t })
+      .input(ws.extend(AssetCreateInput.shape))
+      .output(Asset),
+    update: baseContract
+      .route({ method: 'PATCH', path: '/assets/{assetId}', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), ...AssetPatchInput.shape }))
+      .output(Asset),
+    archive: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/archive', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), archived: z.boolean().default(true) }))
+      .output(Asset),
+  },
+}
+export type InventoryContract = typeof inventoryContract

package/src/contract/settings.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+
+/**
+ * Workspace-level settings for Inventory.
+ *
+ * Deliberately small. Nearly everything an administrator configures belongs to a category, a
+ * location or a field definition, because those are the things that differ between two kinds of
+ * item in the same company. What is left is genuinely workspace-wide.
+ *
+ * Note what is *not* here: the capability switches. Those live under a reserved `$capabilities` key
+ * the platform owns, so turning one off cannot collide with a settings field and cannot be dropped
+ * by a settings round-trip.
+ */
+export const InventorySettings = z.object({
+  /**
+   * What an asset tag looks like. `INV-` and 4 gives `INV-0042`.
+   *
+   * People read these off a sticker and say them out loud, so a workspace that already labels its
+   * laptops `LT-` should not have to keep two numbering systems in its head. The counter itself is a
+   * row in `mod_inventory.counters`, not a setting — a number an administrator can edit is a number
+   * that produces a duplicate tag.
+   */
+  assetCodePrefix: z.string().max(8).default('INV-'),
+  assetCodePad: z.number().int().min(1).max(10).default(4),
+  // `warrantyNoticeDays` used to sit here, describing a warranty sweep that has never existed —
+  // no job, no subscription, nothing reading the number. A setting nothing enforces is the same
+  // lie as a capability nothing checks: it teaches an administrator that the settings page does
+  // not mean anything. It comes back with the sweep.
+})
+export type InventorySettings = z.infer<typeof InventorySettings>

package/src/module.test.ts

@@ -13,9 +13,16 @@
  */
 import type { Kernel } from '@kernhq/kernel'
 import { describe, expect, it } from 'vitest'
-import { inventoryContract, inventoryEvents, inventoryPermissions, MODULE_ID } from './contract.js'
-import { implement_ } from './server/_impl.js'
+import {
+  inventoryCapabilities,
+  inventoryCapabilityProcedures,
+  inventoryContract,
+  inventoryEvents,
+  inventoryPermissions,
+  MODULE_ID,
+} from './contract/index.js'
 import { inventoryModule } from './server/index.js'
+import { inventoryRouter } from './server/router.js'
 
 /** An oRPC procedure (contract or implementation) carries `~orpc`; a router group does not. */
 interface Leaf {
@@ -38,7 +45,7 @@ function leaves(node: unknown, path: string[] = []): Record<string, Leaf> {
 
 // The router is only inspected, never called, so it needs no real kernel behind it.
 const declared = leaves(inventoryContract)
-const implemented = leaves(implement_({} as Kernel))
+const implemented = leaves(inventoryRouter({} as Kernel))
 
 describe('the contract and the router agree', () => {
   it('implements every declared procedure, and nothing that was never declared', () => {
@@ -54,11 +61,89 @@ describe('the contract and the router agree', () => {
   })
 })
 
+/**
+ * Which middleware is which — established by what each one *does*, because there is nothing else to
+ * go on.
+ *
+ * `workspaceScoped`, `requiresCapability` and `requires` all come back from oRPC as a function
+ * named `decorated` carrying identical own properties: no name, no tag, nothing to compare. So each
+ * middleware is called here against a kernel stub that records what it reached for, and what it
+ * reached for is its identity.
+ *
+ * This is what replaced `middlewares.length >= 2`, which was satisfied by *any* two middlewares —
+ * a procedure that had lost `workspaceScoped` and kept two permission checks passed it, and that is
+ * precisely the failure this file's docblock claims to prevent. A count is not an assertion about
+ * authorisation; it is an assertion about arithmetic.
+ */
+interface Reached {
+  /** the module id `workspaceScoped` asked `isModuleEnabled` about */
+  module?: string
+  /** the permission `requires` asked `authz.require` for */
+  permission?: string
+  /** the `<module>.<capability>` `requiresCapability` looked up */
+  capability?: string
+}
+
+type MiddlewareFn = (
+  options: { context: unknown; next: (options?: unknown) => Promise<unknown> },
+  input: unknown,
+) => Promise<unknown>
+
+const WORKSPACE = '00000000-0000-4000-8000-000000000000'
+
+async function reachedFor(middleware: unknown): Promise<Reached> {
+  const seen: Reached = {}
+  const kernel = {
+    authz: {
+      requireMember: () => undefined,
+      require: async (_principal: unknown, permission: string) => {
+        seen.permission = permission
+      },
+    },
+    isModuleEnabled: async (_workspaceId: string, moduleId: string) => {
+      seen.module = moduleId
+      return true
+    },
+    // The real one answers a Set; a stub only has to record which capability was asked about.
+    capabilities: async (_workspaceId: string, moduleId: string) => ({
+      has: (capability: string) => {
+        seen.capability = `${moduleId}.${capability}`
+        return true
+      },
+    }),
+  }
+  const principal = { kind: 'user', userId: WORKSPACE, instanceAdmin: false, memberships: [] }
+  await (middleware as MiddlewareFn)(
+    { context: { kernel, principal }, next: async () => ({}) },
+    { workspaceId: WORKSPACE },
+  )
+  return seen
+}
+
+const chainOf = (name: string): unknown[] => implemented[name]?.['~orpc'].middlewares ?? []
+
 describe('every procedure is authorised', () => {
-  it('carries both the workspace/module gate and a permission check', () => {
-    for (const [name, leaf] of Object.entries(implemented)) {
-      // `workspaceScoped(MODULE_ID)` + `requires('<permission>')`
-      expect(leaf['~orpc'].middlewares?.length ?? 0, `${name} middlewares`).toBeGreaterThanOrEqual(2)
+  const declaredKeys = new Set(inventoryPermissions.map((p) => p.key))
+
+  it('puts the workspace and module gate first, on every procedure', async () => {
+    for (const name of Object.keys(implemented)) {
+      const [first] = chainOf(name)
+      expect(
+        first === undefined ? undefined : (await reachedFor(first)).module,
+        `${name}: the first middleware has to be workspaceScoped('${MODULE_ID}') — a real membership, and the module switched on for that workspace`,
+      ).toBe(MODULE_ID)
+    }
+  })
+
+  it('puts a permission check the module declares after it', async () => {
+    for (const name of Object.keys(implemented)) {
+      const asked = (await Promise.all(chainOf(name).slice(1).map(reachedFor)))
+        .map((r) => r.permission)
+        .filter((p) => p !== undefined)
+      expect(
+        asked.filter((p) => declaredKeys.has(p)),
+        `${name}: needs requires(<a permission this module declares>) after the workspace gate; it asked for ${JSON.stringify(asked)}`,
+      ).not.toHaveLength(0)
     }
   })
 })
@@ -74,6 +159,54 @@ describe('the module declares what it uses', () => {
     expect(inventoryModule.definition.id).toBe(MODULE_ID)
     expect(inventoryModule.definition.permissions).toBe(inventoryPermissions)
     expect(inventoryModule.definition.events).toBe(inventoryEvents)
+    expect(inventoryModule.definition.capabilities).toBe(inventoryCapabilities)
     expect(inventoryModule.router, 'a module with a contract has to mount a router').toBeTypeOf('function')
   })
 })
+
+/**
+ * Capabilities, which are the one thing here that cannot be seen by reading a handler.
+ *
+ * A missing `requiresCapability` is invisible: the procedure compiles, every other test passes, and
+ * the only symptom is a workspace successfully calling a feature it switched off. So the map is
+ * declared as data in the contract and checked against the router here.
+ *
+ * The map is empty while `core` is the only capability — `core` is `required`, so nothing sits
+ * behind a switch anyone can flip. These tests are what keep that true as the map fills up.
+ */
+describe('capabilities are enforced where they are declared', () => {
+  const gated = new Set(Object.values(inventoryCapabilityProcedures).flat())
+
+  it('names only capabilities the module actually declares', () => {
+    const declaredIds = new Set(inventoryCapabilities.map((c) => c.id))
+    for (const id of Object.keys(inventoryCapabilityProcedures))
+      expect({ id, declared: declaredIds.has(id) }).toEqual({ id, declared: true })
+  })
+
+  it('names only procedures the contract actually has', () => {
+    for (const name of gated) expect({ name, exists: name in declared }).toEqual({ name, exists: true })
+  })
+
+  it('gates every procedure that belongs to a capability on that capability', async () => {
+    // Identity again, not a count: a third middleware proves nothing about which capability — or
+    // whether a capability — is being checked. `workspaceScoped` -> `requiresCapability` ->
+    // `requires`, in that order, so a workspace with the whole module off is refused before
+    // anything reveals which capabilities it would have had.
+    for (const [capability, names] of Object.entries(inventoryCapabilityProcedures)) {
+      for (const name of names) {
+        const chain = await Promise.all(chainOf(name).map(reachedFor))
+        const gate = chain.findIndex((r) => r.capability === `${MODULE_ID}.${capability}`)
+        const permission = chain.findIndex((r) => r.permission !== undefined)
+        expect(gate, `${name}: needs requiresCapability('${MODULE_ID}', '${capability}')`).toBeGreaterThan(0)
+        expect(gate, `${name}: the capability gate belongs before the permission check`).toBeLessThan(
+          permission,
+        )
+      }
+    }
+  })
+
+  it('leaves `core` off the map, because a required capability is not a switch', () => {
+    expect(inventoryCapabilityProcedures.core).toBeUndefined()
+    expect(inventoryCapabilities.find((c) => c.id === 'core')?.required).toBe(true)
+  })
+})

package/src/server/index.ts

@@ -1,7 +1,14 @@
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { inventoryContract, inventoryEvents, inventoryPermissions, MODULE_ID } from '../contract.js'
-import { defineModule, defineServerModule, implement_, packageVersion } from './_impl.js'
+import {
+  InventorySettings,
+  inventoryCapabilities,
+  inventoryContract,
+  inventoryEvents,
+  inventoryPermissions,
+  MODULE_ID,
+} from '../contract/index.js'
+import { defineModule, defineServerModule, inventoryRouter, packageVersion } from './router.js'
 import { schema } from './schema.js'
 
 export const inventoryModule = defineServerModule({
@@ -10,24 +17,20 @@ export const inventoryModule = defineServerModule({
     name: 'Inventory',
     version: packageVersion(import.meta.url),
     description:
-      'The asset register: what the company owns, who holds each item, and everything that happened to it',
+      'The asset register: what the company owns, item by item — tags, serial numbers, purchase and warranty details',
     icon: 'briefcase',
     permissions: inventoryPermissions,
+    capabilities: inventoryCapabilities,
     events: inventoryEvents,
+    settings: InventorySettings,
+    // `objectTypes` returns with the resolver that turns a mention or a link into an asset and the
+    // indexer that puts one in search — declaring the type with neither made both resolve to
+    // nothing, which reads to a user as a broken link rather than as a feature not built yet.
   }),
   /** Attached so the developer panel can check the router against what was promised. */
   contract: inventoryContract,
   schema,
   migrationsFolder: join(dirname(fileURLToPath(import.meta.url)), '../../migrations'),
-  router: implement_,
-  /**
-   * What this module reacts to. The pattern may be an exact name, `module.*`, or `*`; handlers are
-   * durable consumers in production, so one that throws is retried rather than lost.
-   */
-  subscriptions: {
-    'core.workspace.created': async (event, kernel) => {
-      kernel.log.info({ module: MODULE_ID, event: event.name }, 'a workspace was created')
-    },
-  },
+  router: inventoryRouter,
 })
 export default inventoryModule