@kernhq/module-inventory 0.3.0 → 0.4.0

package/src/contract/models.ts

@@ -51,8 +51,17 @@ export const Category = z.object({
   id: z.uuid(),
   workspaceId: WorkspaceId,
   name: z.string().min(1).max(120),
-  /** Where it sits in a picker. Equal orders fall back to the name, so a workspace that never
-   *  reorders anything still gets an alphabetical list rather than an arbitrary one. */
+  /**
+   * Where it sits in the sequence. **Storage, not a setting.**
+   *
+   * Nobody thinks about their categories as integers, so no screen shows this number and no input
+   * accepts one: `categories.reorder` takes the ids in the order somebody dragged them into and
+   * renumbers the live ones `0…n-1` in one transaction. `create` and a restore append, so two live
+   * categories never share a value — which is the state a "position" field invited on every save.
+   *
+   * The name is still the tiebreak in `list`, because a workspace seeded before this existed, or a
+   * row written by hand, can still hold a duplicate; it just stops being the ordinary case.
+   */
   order: z.number().int(),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -60,12 +69,36 @@ export const Category = z.object({
 })
 export type Category = z.infer<typeof Category>
 
+/**
+ * What a person types when they add or rename a category: a name, and nothing else.
+ *
+ * `order` used to be here, optional, and it was the only way to move a category — a number field on
+ * a settings form, with a hint explaining that lower comes first and that ties fall back to names.
+ * The sequence is written by `categories.reorder` now, so an `order` on create or update would be a
+ * second way to set the same thing, disagreeing with the first the moment anybody used it.
+ */
 export const CategoryInput = z.object({
   name: z.string().trim().min(1).max(120),
-  order: z.number().int().min(0).max(9999).optional(),
 })
 export type CategoryInput = z.infer<typeof CategoryInput>
 
+/**
+ * How many categories one workspace may have live at once — and the reason it is a *stated* limit.
+ *
+ * `categories.reorder` has to name every live category exactly once, so its input array needs a
+ * bound; every zod array that a client fills does, or a single request can ask the server to hold an
+ * arbitrary list in memory. A bound on that array alone is a **silent ceiling**: a workspace with
+ * more live categories than the number could still create, rename and archive them, and only
+ * reordering would fail — the one procedure with no other way to do the job.
+ *
+ * So the same number is enforced where somebody meets it. `categories.create` and a restore both
+ * refuse with `inventory.category.limit_reached` once a workspace holds this many live categories,
+ * which is a sentence naming the number at the moment it matters. Archiving one frees a place, which
+ * is why the limit counts the **live** rows rather than every row ever made: the advice the refusal
+ * gives has to be true.
+ */
+export const MAX_LIVE_CATEGORIES = 500
+
 /**
  * One stretch of time during which one person held one asset.
  *

package/src/contract/router.ts

@@ -13,6 +13,7 @@ import {
   CustodyPeriod,
   CustodyResult,
   InventoryStats,
+  MAX_LIVE_CATEGORIES,
   RepairInput,
   RepairListItem,
   RepairPatchInput,
@@ -163,6 +164,34 @@ export const inventoryContract = {
       .route({ method: 'POST', path: '/categories/{categoryId}/archive', tags: t })
       .input(ws.extend({ categoryId: z.uuid(), archived: z.boolean().default(true) }))
       .output(Category),
+    /**
+     * The whole sequence, in the order somebody put it in — the only thing that writes `order`.
+     *
+     * **The ids, not positions.** A position number is a database column with a form around it: two
+     * categories can hold the same one, nobody thinks about their filing as integers, and the screen
+     * that asked for one had to explain how ties break. A list of ids says exactly what the person
+     * did, whatever they did it with — a drag, or the move-up and move-down buttons beside it.
+     *
+     * **It must name every live category the workspace has, exactly once.** A partial list is not
+     * treated as "leave the rest alone": somebody added a category in another tab while this page
+     * was open, and the ordering in hand no longer describes the workspace. Renumbering what it does
+     * name would drop the new one somewhere nobody chose, silently — so the whole call is refused
+     * with `inventory.category.order_stale` and the page reloads and asks again. Naming an archived
+     * category is the same mistake from the other side and gets the same answer; an id from another
+     * workspace is `NOT_FOUND`, exactly as `update` and `archive` answer for one.
+     *
+     * Answers the live sequence as it now stands, so a caller needs no second read.
+     *
+     * **The bound is `MAX_LIVE_CATEGORIES`, and it is the same number `create` refuses at.** A bound
+     * on this array with nothing enforcing it elsewhere is a silent ceiling: a workspace could grow
+     * past it one category at a time and then find that the only procedure that can order them is
+     * the one it can no longer call. Held to the same number at the point of creation, the array can
+     * always name every live category a workspace is allowed to have.
+     */
+    reorder: baseContract
+      .route({ method: 'POST', path: '/categories/reorder', tags: t })
+      .input(ws.extend({ categoryIds: z.array(z.uuid()).min(1).max(MAX_LIVE_CATEGORIES) }))
+      .output(z.array(Category)),
   },
 
   /**

package/src/module.test.ts

@@ -399,4 +399,27 @@ describe('the platform surfaces the module declares', () => {
     for (const { type } of inventoryModule.definition.notificationTypes ?? [])
       expect({ type, sent: sources.includes(`'${type}'`) }).toEqual({ type, sent: true })
   })
+
+  /**
+   * The client manifest's `name` is read on screen, so it has to be a getter over `t`.
+   *
+   * The dashboard's widget picker heads this module's group with `mod.name` directly, and the shell's
+   * settings rail falls back to it for a module whose navigation it cannot read — so an English
+   * literal there is a Latin word sitting in an otherwise Persian panel. `name` is typed as a plain
+   * `string` on `ClientModule`, which is exactly why nothing else catches this: a literal and a
+   * getter are the same type.
+   *
+   * Read as text rather than imported, and honest about being crude. `src/client/module.ts` reaches
+   * `@kernhq/ui`, which drags a Svelte compiler into whatever imports it, and this package's vitest
+   * runs plain Node — the same reason `errors.ts` and `messages.ts` are kept importable and the
+   * components are not. It proves the shape, not the rendering.
+   */
+  it('gives the client manifest a translated name rather than an English literal', () => {
+    const here = dirname(fileURLToPath(import.meta.url))
+    const source = readFileSync(join(here, 'client', 'module.ts'), 'utf8')
+    expect(source, 'a getter, so the language is the one on screen at read time').toMatch(
+      /get name\(\)\s*\{\s*return t\('nav'\)/,
+    )
+    expect(source, 'and no literal left beside it').not.toMatch(/^\s*name: '/m)
+  })
 })