@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/server/services/search.ts

@@ -0,0 +1,166 @@
+import type { core } from '@kernhq/contracts'
+import type { Kernel, Tx } from '@kernhq/kernel'
+import { and, eq, isNull, sql } from 'drizzle-orm'
+import { MODULE_ID } from '../../contract/models.js'
+import { assets, categories } from '../schema.js'
+import type { NotifyService } from './notify.js'
+
+/** One page of the full reindex. Big enough to be worth a round trip, small enough to hold. */
+const SCAN_BATCH = 500
+
+/**
+ * How an asset is referred to from outside this module.
+ *
+ * One function, because a search hit and a resolved `inventory:asset:<id>` reference have to be the
+ * same thing — somebody who finds a laptop in the command palette and somebody who follows a link to
+ * it from a chat message are looking at the same row and must see the same words for it.
+ */
+export const assetUrl = (assetId: string) => `/inventory?asset=${assetId}`
+export const ASSET_ICON = 'briefcase'
+
+/** The columns a document is built from, and the one join it needs. */
+export interface IndexableAsset {
+  asset: typeof assets.$inferSelect
+  /** The category's name, resolved at read time — never copied into `assets`, so a rename lands. */
+  categoryName: string | null
+}
+
+/**
+ * What a person types into the command palette, and what an asset has to answer it with.
+ *
+ * An asset tag read off a sticker is the first of these — `INV-0042` is what somebody has in their
+ * hand — so it leads the title, exactly as tracker leads with an issue key. The rest is everything
+ * printed on or near the thing: its name, its serial number, where it is kept, and what the
+ * workspace files it under.
+ *
+ * **The category is indexed by name, not by id.** "chair" finds every chair filed under Furniture
+ * only if the word Furniture is in the document; an id in `attributes` is a filter, not a search
+ * term. The cost is that renaming a category leaves its assets' documents naming the old word until
+ * each one is next written, which is a staleness worth stating and not worth a workspace-wide
+ * rewrite on every rename — `core.search.reindex` is the thing that fixes it, and it exists.
+ *
+ * `acl` is null: an asset is visible to anybody with `inventory.asset.view`, which is a workspace
+ * permission and not a per-row one, so there is no narrower audience to name.
+ */
+export function assetSearchDocument(workspaceId: string, row: IndexableAsset): core.SearchDocument {
+  const body = [row.asset.description, row.asset.serialNumber, row.asset.location, row.categoryName]
+    .map((part) => part?.trim())
+    .filter((part): part is string => Boolean(part))
+    .join('\n')
+  return {
+    workspaceId: workspaceId as core.SearchDocument['workspaceId'],
+    object: { module: MODULE_ID, type: 'asset', id: row.asset.id },
+    title: `${row.asset.code} ${row.asset.name}`,
+    body: body || null,
+    url: assetUrl(row.asset.id),
+    icon: ASSET_ICON,
+    acl: null,
+    updatedAt: row.asset.updatedAt.toISOString(),
+    attributes: {
+      code: row.asset.code,
+      status: row.asset.status,
+      categoryId: row.asset.categoryId,
+      custodianUserId: row.asset.custodianUserId,
+    },
+  }
+}
+
+/** The one select every read here makes: the asset, plus its category's current name. */
+const withCategoryName = (tx: Tx) =>
+  tx
+    .select({ asset: assets, categoryName: categories.name })
+    .from(assets)
+    .leftJoin(
+      categories,
+      and(eq(categories.id, assets.categoryId), eq(categories.workspaceId, assets.workspaceId)),
+    )
+
+/**
+ * Putting assets into the workspace-wide search index, and taking them out again.
+ *
+ * `NotifyService` has carried `index`/`unindex` since the module was written and nothing called
+ * either, because `objectTypes` had been taken off the manifest — a declared type with no indexer
+ * and no resolver renders a link to nothing, which reads to a person as a broken product rather
+ * than as a feature that has not shipped. Both halves arrive together here.
+ *
+ * Every method is best-effort by way of `NotifyService`: an asset must not fail to save because the
+ * core search service is briefly away. The register's own row is authoritative and a later
+ * `core.search.reindex` repairs whatever was missed, which is exactly what that job is for.
+ */
+export class SearchService {
+  constructor(
+    private readonly kernel: Kernel,
+    private readonly notify: NotifyService,
+  ) {}
+
+  /**
+   * One asset as a document, or `null` for one the index should not hold.
+   *
+   * `null` for a row that is gone **and** for one that is archived, because the indexer treats null
+   * as "remove this": an archived asset is one the workspace has said it no longer tracks, so
+   * finding it in the command palette would offer a door to something deliberately put away.
+   * Restoring it writes the row again, which reindexes it.
+   */
+  async load(workspaceId: string, assetId: string): Promise<core.SearchDocument | null> {
+    return this.kernel.database.withWorkspace(workspaceId, async (tx) => {
+      const [row] = await withCategoryName(tx)
+        .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+        .limit(1)
+      if (!row || row.asset.archivedAt) return null
+      return assetSearchDocument(workspaceId, row)
+    })
+  }
+
+  /**
+   * Every live asset of a workspace, in pages, for a full reindex.
+   *
+   * Keyset by id rather than `offset`: a scan of a big workspace runs for a while, and an offset
+   * walk over a table somebody is writing to repeats and drops rows. Ids are uuidv7 and unique, so
+   * one column is a page boundary two rows cannot share — the same reasoning `assets.list` gives.
+   *
+   * One transaction per page rather than one for the whole scan: holding a pooled connection open
+   * across a reindex of ten thousand rows is how a service runs out of connections doing
+   * maintenance.
+   */
+  async *scan(workspaceId: string): AsyncIterable<core.SearchDocument> {
+    let cursor: string | null = null
+    for (;;) {
+      const rows: IndexableAsset[] = await this.kernel.database.withWorkspace(workspaceId, (tx) =>
+        withCategoryName(tx)
+          .where(
+            and(
+              eq(assets.workspaceId, workspaceId),
+              isNull(assets.archivedAt),
+              cursor ? sql`${assets.id} > ${cursor}` : sql`true`,
+            ),
+          )
+          .orderBy(assets.id)
+          .limit(SCAN_BATCH),
+      )
+      if (!rows.length) return
+      for (const row of rows) yield assetSearchDocument(workspaceId, row)
+      cursor = rows.at(-1)?.asset.id ?? null
+    }
+  }
+
+  /**
+   * Bring the index into step with one asset, whichever direction that means.
+   *
+   * Called after the transaction has committed, never inside it — the index is another service's
+   * table, and telling it about a row a rollback then took away cannot be retracted. It is the
+   * reason `router.ts` announces from outside the transaction and this is announced beside the
+   * event and the realtime change.
+   */
+  async reindex(workspaceId: string, assetId: string): Promise<void> {
+    const document = await this.load(workspaceId, assetId).catch((err) => {
+      this.kernel.log.warn(
+        { err: err instanceof Error ? err.message : err, workspaceId, assetId },
+        'inventory: could not read an asset to reindex it',
+      )
+      return undefined
+    })
+    if (document === undefined) return
+    if (document) await this.notify.index([document])
+    else await this.notify.unindex(workspaceId, 'asset', [assetId])
+  }
+}

package/src/server/services/stats.ts

@@ -0,0 +1,88 @@
+import type { Tx } from '@kernhq/kernel'
+import { and, eq, isNull, sql } from 'drizzle-orm'
+import { AssetStatus, type InventoryStats } from '../../contract/models.js'
+import { assets, repairs } from '../schema.js'
+
+/**
+ * The register in numbers.
+ *
+ * It exists because the assets page had no honest number to print. `assets.list` is keyset-paged and
+ * never counts, so the count line said "50 assets" for a workspace with 214 of them and then "100
+ * assets" after *Load more* — a number that is simply wrong, on the line whose whole job is to be
+ * the number. A `count(*)` bolted onto every list page would be the expensive answer to that; one
+ * cheap procedure the page calls once is the right one, and it also gives the dashboard card
+ * something worth showing.
+ *
+ * **`total` counts what the list shows by default — live rows.** `archived` sits beside it rather
+ * than inside it, because a count line that silently included archived rows would disagree with the
+ * list underneath it.
+ */
+export class StatsService {
+  /**
+   * @param repairsOn whether this workspace has the `repairs` capability. Resolved by the caller
+   * *before* the transaction opens, because it is a settings read over the broker.
+   */
+  async summary(tx: Tx, workspaceId: string, repairsOn: boolean): Promise<InventoryStats> {
+    const [totals] = await tx
+      .select({
+        total: sql<number>`count(*) filter (where ${assets.archivedAt} is null)`.mapWith(Number),
+        archived: sql<number>`count(*) filter (where ${assets.archivedAt} is not null)`.mapWith(Number),
+        unassigned:
+          sql<number>`count(*) filter (where ${assets.archivedAt} is null and ${assets.custodianUserId} is null)`.mapWith(
+            Number,
+          ),
+      })
+      .from(assets)
+      .where(eq(assets.workspaceId, workspaceId))
+
+    const grouped = await tx
+      .select({ status: assets.status, n: sql<number>`count(*)`.mapWith(Number) })
+      .from(assets)
+      .where(and(eq(assets.workspaceId, workspaceId), isNull(assets.archivedAt)))
+      .groupBy(assets.status)
+
+    /**
+     * Zero-filled over the whole enum, so a screen can render the set without asking which statuses
+     * happen to exist in this workspace. A missing key and a zero look the same on a card and are
+     * not the same thing to a `Record`.
+     */
+    const byStatus = Object.fromEntries(
+      AssetStatus.options.map((status) => [status, 0]),
+    ) as InventoryStats['byStatus']
+    for (const row of grouped) if (row.status in byStatus) byStatus[row.status as AssetStatus] = row.n
+
+    return {
+      total: totals?.total ?? 0,
+      archived: totals?.archived ?? 0,
+      byStatus,
+      outForRepair: repairsOn ? await this.away(tx, workspaceId) : null,
+      unassigned: totals?.unassigned ?? 0,
+    }
+  }
+
+  /**
+   * How many live items are at a repairer, counted from the **repair rows** rather than from
+   * `assets.status`.
+   *
+   * `byStatus.under_repair` is the same number, and deliberately arrives a different way: that one
+   * reads the cached column every list filters on, this one reads the fact the column is derived
+   * from. `deriveStatus` is what keeps them equal, and `inventory.int.test.ts` asserts they are —
+   * which is a real check on the derivation rather than two ways of writing the same query.
+   *
+   * **Joined to `assets` for the live rows, which it did not used to be.** The old version leaned on
+   * `AssetService.archive` refusing to retire an item that is away, so every open repair was assumed
+   * to belong to a live asset. That refusal is now withdrawn while the workspace has the `repairs`
+   * capability off — it named a procedure answering 404, and leaving it in place is what stranded
+   * the asset — so an archived row with an open repair is reachable, and `byStatus.under_repair`
+   * (live rows only) would have disagreed with this number the moment the capability came back on.
+   * Two counts of one thing have to be counted over one set.
+   */
+  private async away(tx: Tx, workspaceId: string): Promise<number> {
+    const [row] = await tx
+      .select({ n: sql<number>`count(*)`.mapWith(Number) })
+      .from(repairs)
+      .innerJoin(assets, and(eq(assets.id, repairs.assetId), eq(assets.workspaceId, repairs.workspaceId)))
+      .where(and(eq(repairs.workspaceId, workspaceId), isNull(repairs.returnedOn), isNull(assets.archivedAt)))
+    return row?.n ?? 0
+  }
+}

package/src/server/services/status.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { deriveStatus } from './status.js'
+
+/**
+ * The one rule that two services would otherwise each write their own version of.
+ *
+ * `CustodyService.stamp` wrote `userId ? 'assigned' : 'in_stock'` unconditionally before repairs
+ * existed, which is correct right up to the moment an item can be somewhere. This is the arithmetic
+ * of `status`, tested where it is cheap; `inventory.int.test.ts` proves the same combinations end to
+ * end through the procedures that write them.
+ */
+describe('deriveStatus', () => {
+  it('is in stock when nobody has it and nothing is being fixed', () => {
+    expect(deriveStatus({ custodianUserId: null, awayForRepair: false })).toBe('in_stock')
+  })
+
+  it('is assigned when somebody has it', () => {
+    expect(deriveStatus({ custodianUserId: 'ada', awayForRepair: false })).toBe('assigned')
+  })
+
+  it('is under repair whether or not somebody still has it', () => {
+    // The whole point of the rule: a repair says *where* the thing is, and custody says *who is
+    // answerable for it*. A laptop at the workshop is still Dan's, and the status has to show the
+    // thing somebody looking for it needs to know.
+    expect(deriveStatus({ custodianUserId: null, awayForRepair: true })).toBe('under_repair')
+    expect(deriveStatus({ custodianUserId: 'dan', awayForRepair: true })).toBe('under_repair')
+  })
+
+  it('goes back to the custodian rather than to stock when a repair ends', () => {
+    // The failure this prevents is silent: completing a repair straight to `in_stock` releases
+    // whoever was answerable for the item without anybody deciding to.
+    expect(deriveStatus({ custodianUserId: 'dan', awayForRepair: false })).toBe('assigned')
+  })
+})

package/src/server/services/status.ts

@@ -0,0 +1,143 @@
+import { KernError, type Tx } from '@kernhq/kernel'
+import { and, eq, isNull } from 'drizzle-orm'
+import type { AssetStatus } from '../../contract/models.js'
+import { assets, repairs } from '../schema.js'
+
+/**
+ * What an asset's status is, decided in one place from the facts that decide it.
+ *
+ * `assets.status` is stored rather than computed, because every list filter asks for it — but it is
+ * **derived**, and the moment two services each wrote their own version of the derivation they
+ * disagreed. That is not hypothetical: `CustodyService.stamp` wrote `userId ? 'assigned' :
+ * 'in_stock'` unconditionally, so handing over a laptop that was sitting at the repairer would have
+ * announced it as back in the office. Both services now read this function, so there is one answer
+ * and a test can hold it.
+ *
+ * ## The rule, written down because it is a decision rather than an inevitability
+ *
+ * **Custody and repair are independent facts, and repair wins the status column.** An item can be
+ * out for repair *while still assigned to somebody*: Dan's laptop goes to the workshop, Dan is still
+ * answerable for it, the custody period stays open and `custodian_user_id` stays set. Only `status`
+ * moves, because `status` is the column that answers *where is it*, and "with a repairer" is the
+ * answer somebody looking for it needs. Custody is answered by `custodian_user_id`, which is a
+ * different column and is not touched.
+ *
+ * Two consequences follow, and both are deliberate:
+ *
+ * - **No custody procedure refuses an item that is away for repair.** Refusing `assign` would mean
+ *   refusing `return` too, and somebody leaving the company while their laptop is at the workshop
+ *   must still be able to hand it back. All three verbs recompute the status through this function
+ *   instead, so a return during a repair leaves the item `under_repair` with nobody holding it,
+ *   which is exactly true.
+ * - **Completing a repair does not blindly go to `in_stock`.** It goes back to whatever custody
+ *   says — `assigned` when somebody still holds it — because the repair never released them.
+ *
+ * `reserved`, `lost` and `retired` are not derivable from anything this module records: they are set
+ * by hand by the features that will own them, and nothing writes them today. When something does,
+ * it either belongs in this function with a fact of its own or it does not belong in this column.
+ *
+ * ## The third fact, which is not about the item at all
+ *
+ * **`under_repair` belongs to the `repairs` capability, so a workspace that has switched repairs
+ * off never has an asset in it.** That is not cosmetic tidying, it is the thing that stopped an
+ * asset being stranded: with the capability off, `repairs.complete` answers 404, so the row that
+ * decides `under_repair` can never be closed — and the item sat in a status nothing could move it
+ * out of, behind an archive that refused it for the same reason. Reading the switch here is what
+ * makes the capability reversible in both directions rather than one: switch repairs off and the
+ * next thing that touches the asset derives its status from custody alone; switch it back on and
+ * the open repair asserts itself again, because nothing was destroyed to get out of it.
+ *
+ * The switch is read *before* the transaction opens, like every other settings lookup in this
+ * module, and handed down as `repairsOn` — a `kernel.settings` call is a broker round trip and
+ * awaiting one while holding a pooled connection is the failure `AssetService.codeFormat`
+ * documents. `jobs.ts` reconciles the rows nobody happens to touch.
+ */
+export interface StatusFacts {
+  /** `assets.custodian_user_id` — who is answerable for it, which a repair does not change. */
+  custodianUserId: string | null
+  /** An **open repair this workspace is recording** — see `awayForRepair` below. */
+  awayForRepair: boolean
+}
+
+export function deriveStatus(facts: StatusFacts): AssetStatus {
+  if (facts.awayForRepair) return 'under_repair'
+  return facts.custodianUserId ? 'assigned' : 'in_stock'
+}
+
+/**
+ * Is this item away for a repair the workspace still records?
+ *
+ * Two facts, and the capability is checked first so the query is skipped entirely for a workspace
+ * that does not record repairs. Every caller that decides a status goes through this rather than
+ * through `openRepairId` directly, so there is one answer to "is it away" and a test can hold it.
+ */
+export async function awayForRepair(
+  tx: Tx,
+  workspaceId: string,
+  assetId: string,
+  repairsOn: boolean,
+): Promise<boolean> {
+  if (!repairsOn) return false
+  return (await openRepairId(tx, workspaceId, assetId)) !== undefined
+}
+
+/**
+ * The open repair for one asset, if there is one — the query behind `awayForRepair`.
+ *
+ * At most one exists by construction: `inventory_repairs_one_open_uq` is a unique index on
+ * `(asset_id) where returned_on is null`. It lives here rather than in `RepairService` so that
+ * `CustodyService` can read the fact without depending on the whole repair service, and so that
+ * every caller decides a status the same way — read both facts, then call `deriveStatus`, never
+ * assume one of them.
+ */
+/**
+ * The asset row, locked for the rest of the transaction — the serialisation point for `status`.
+ *
+ * **`status` is derived from two facts written by two different services, so the derivation needs a
+ * lock even though neither fact does.** `CustodyService` decides it from custody *and* the open
+ * repair; `RepairService` decides it from the repair *and* the custodian. Each used to read the
+ * other's fact without a lock, so a handover and a repair completing at the same instant
+ * interleaved into a status that matched neither: the second writer had read the first one's fact
+ * before it was written, derived from a snapshot that no longer existed, and overwrote the answer.
+ * That is a lost update in the plain sense — two transactions, one column, one of them silently
+ * discarded.
+ *
+ * Both paths now take this lock **before** reading either fact, so the second one waits, re-reads
+ * what the first committed, and derives from the state that actually exists. `for('update')`
+ * re-evaluates the row at the latest committed version once the lock is granted, which is exactly
+ * what makes the re-read honest rather than a repeat of the stale snapshot.
+ *
+ * **It is not the arbiter of "already held" or "already away".** Those stay with the exclusion
+ * constraint and the partial unique index, for the reason both services' docblocks give: locking
+ * the asset first would serialise two handovers into two *successful* handovers. This lock is taken
+ * after the row that decides the race has been written, so it orders the bookkeeping without
+ * deciding the contest.
+ */
+export async function lockAsset(
+  tx: Tx,
+  workspaceId: string,
+  assetId: string,
+): Promise<typeof assets.$inferSelect> {
+  const [row] = await tx
+    .select()
+    .from(assets)
+    .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+    .for('update')
+  if (!row) throw KernError.notFound('Asset')
+  return row
+}
+
+export async function openRepairId(
+  tx: Tx,
+  workspaceId: string,
+  assetId: string,
+): Promise<string | undefined> {
+  const [row] = await tx
+    .select({ id: repairs.id })
+    .from(repairs)
+    .where(
+      and(eq(repairs.workspaceId, workspaceId), eq(repairs.assetId, assetId), isNull(repairs.returnedOn)),
+    )
+    .limit(1)
+  return row?.id
+}

package/tsconfig.base.json

@@ -0,0 +1,22 @@
+{
+  "extends": "@kernhq/tsconfig/base.json",
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": false,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "useDefineForClassFields": true
+  }
+}

package/tsconfig.client.json

@@ -6,5 +6,5 @@
     "moduleResolution": "Bundler",
     "lib": ["ES2023", "DOM", "DOM.Iterable"]
   },
-  "include": ["src/client/**/*.ts", "src/client/**/*.svelte", "src/contract.ts"]
+  "include": ["src/client/**/*.ts", "src/client/**/*.svelte", "src/contract/**/*.ts"]
 }

package/tsconfig.json

@@ -5,6 +5,6 @@
     "outDir": "dist",
     "types": ["node"]
   },
-  "include": ["src/contract.ts", "src/server"],
+  "include": ["src/contract", "src/server"],
   "exclude": ["src/**/*.test.ts"]
 }

package/vitest.config.ts

@@ -1,5 +1,20 @@
 import { defineConfig } from 'vitest/config'
 
-// `passWithNoTests` so a copy of this package that has not written its first test yet still reports a
-// green `pnpm test` for the whole workspace instead of failing on "no test files found".
-export default defineConfig({ test: { include: ['src/**/*.test.ts'], passWithNoTests: true } })
+/**
+ * `passWithNoTests` so a copy of this package that has not written its first test yet still reports
+ * a green `pnpm test` instead of failing on "no test files found".
+ *
+ * The timeouts and `fileParallelism: false` are for the integration suite: it creates a scratch
+ * database per file, applies every migration and drops it again. Two files doing that at once
+ * against one server is slower than doing it in turn, and the default 5s timeout expires during the
+ * migration rather than during anything being tested.
+ */
+export default defineConfig({
+  test: {
+    passWithNoTests: true,
+    include: ['src/**/*.test.ts'],
+    testTimeout: 60_000,
+    hookTimeout: 120_000,
+    fileParallelism: false,
+  },
+})