@kernhq/module-inventory 0.1.2 → 0.3.0

package/migrations/meta/_journal.json

@@ -5,16 +5,58 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1787738327443,
+      "when": 1787759199523,
       "tag": "0000_init",
       "breakpoints": true
     },
     {
       "idx": 1,
       "version": "7",
-      "when": 1787738328443,
+      "when": 1787759200523,
       "tag": "0001_rls",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1787774484162,
+      "tag": "0002_custody_and_categories",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1787779029775,
+      "tag": "0003_repairs",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1787783383973,
+      "tag": "0004_platform_surfaces",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1787788455672,
+      "tag": "0005_repair_dates",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1787788455673,
+      "tag": "0006_workspace_registry_read",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1787788455674,
+      "tag": "0007_history_sequence",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kernhq/module-inventory",
-  "version": "0.1.2",
-  "description": "Kern inventory module: the company's asset register — what it owns, who holds each item, purchase and warranty details, repairs, and a full history of every change",
+  "version": "0.3.0",
+  "description": "Kern inventory module: the company's asset register — what it owns, item by item, with asset tags, serial numbers, purchase and warranty details",
   "homepage": "https://github.com/KernAIO/module-inventory#readme",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -21,6 +21,7 @@
     "migrations",
     "src",
     "drizzle.config.ts",
+    "tsconfig.base.json",
     "tsconfig.json",
     "tsconfig.client.json",
     "vitest.config.ts",
@@ -63,7 +64,7 @@
     "@kernhq/contracts": "^0.7.0",
     "@kernhq/kernel": "^0.7.0",
     "@kernhq/tsconfig": "^0.1.0",
-    "@kernhq/ui": "^0.10.0",
+    "@kernhq/ui": "^0.12.0",
     "@tanstack/svelte-query": "^6.1.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.15.0",
@@ -77,7 +78,7 @@
   "peerDependencies": {
     "@kernhq/contracts": "^0.7.0",
     "@kernhq/kernel": "^0.7.0",
-    "@kernhq/ui": "^0.10.0",
+    "@kernhq/ui": "^0.12.0",
     "@tanstack/svelte-query": "^6.1.0",
     "svelte": "^5.46.0"
   },

package/src/client/api-instance.ts

@@ -1,6 +1,18 @@
 import { getHost } from '@kernhq/ui'
 import { createInventoryClient, type InventoryApi } from './api.js'
-import { createMockInventoryApi } from './mock.js'
+import { t } from './i18n.js'
+import { createMockInventoryApi, type MockFileFacts } from './mock.js'
+
+/**
+ * The slice of the host's core client the mock needs, named by shape.
+ *
+ * Only in the mock path: the real server asks core for a file's name over the broker before it
+ * records an attachment. `mock.ts` imports nothing and therefore has no client to ask, so the name
+ * is resolved here — where `getHost()` is already in hand — and handed in.
+ */
+interface MockFileApi {
+  files: { get(input: { id: string }): Promise<{ name: string; mimeType?: string; size?: number }> }
+}
 
 /**
  * This module's API client, made once and shared.
@@ -17,7 +29,20 @@ export function getInventoryApi(): InventoryApi {
   if (cached) return cached
   const host = getHost()
   cached = host.isMock
-    ? (createMockInventoryApi() as unknown as InventoryApi)
+    ? (createMockInventoryApi({
+        describeFile: async (fileId): Promise<MockFileFacts> => {
+          try {
+            const file = await (host.api as MockFileApi).files.get({ id: fileId })
+            return { name: file.name, mimeType: file.mimeType ?? null, size: file.size ?? null }
+          } catch {
+            // A demo must not lose a file because its record could not be read; the row still
+            // says something rather than nothing — and says it in the reader's own language. This
+            // was the literal string 'Uploaded file', which is a label this module prints and
+            // therefore one of its strings, not data that arrived from somewhere else.
+            return { name: t('file_unnamed'), mimeType: null, size: null }
+          }
+        },
+      }) as unknown as InventoryApi)
     : createInventoryClient({ baseUrl: host.apiBaseUrl })
   return cached
 }

package/src/client/api.ts

@@ -1,6 +1,6 @@
 import { createModuleClient, type KernClientOptions } from '@kernhq/sdk'
 import type { ContractRouterClient } from '@orpc/contract'
-import type { InventoryContract } from '../contract.js'
+import type { InventoryContract } from '../contract/index.js'
 
 /** The typed client, derived from the contract — no hand-written method list to drift. */
 export type InventoryApi = ContractRouterClient<InventoryContract>

package/src/client/bidi.test.ts

@@ -0,0 +1,148 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { FSI, isolate, isolated, PDI } from './bidi.js'
+
+/**
+ * The rule that stops a Latin value rendering backwards inside a Persian or Arabic sentence.
+ *
+ * Two halves, and the second is the one that lasts. The first checks `isolate()` itself. The second
+ * reads every client source and refuses a `t()` call that interpolates a value without isolating it
+ * — because this defect is invisible in the source, invisible in a type-check, invisible in
+ * English, and only appears as a quote or a full stop at the wrong end of a name on somebody's
+ * screen. A message added next year with a `{name}` in it fails here rather than there.
+ */
+describe('isolate', () => {
+  it('wraps a value in the first-strong isolate pair', () => {
+    expect(isolate('MacBook Pro 14"')).toBe(`${FSI}MacBook Pro 14"${PDI}`)
+  })
+
+  it('leaves an absent value as nothing at all, rather than two invisible characters', () => {
+    // `{name}` at a call site is very often `asset?.name ?? ''`, and a placeholder nothing filled
+    // should leave no trace in the sentence.
+    expect(isolate('')).toBe('')
+    expect(isolate(null)).toBe('')
+    expect(isolate(undefined)).toBe('')
+  })
+
+  it('is idempotent, so a value isolated twice is still one run', () => {
+    // `history_cleared` passes a `field` that is already `t(key)` or an isolated column name, and
+    // `isolated({ field })` runs over it again. An unbalanced nest would reorder the sentence.
+    expect(isolate(isolate('INV-0042'))).toBe(isolate('INV-0042'))
+  })
+
+  it('strips embedding controls that rode along on a pasted value', () => {
+    // The same characters `price.ts` strips before parsing a number: they arrive by copying out of
+    // an RTL document, and an unbalanced one inside an isolate reorders the rest of the sentence.
+    expect(isolate('‫C02X1234')).toBe(`${FSI}C02X1234${PDI}`)
+  })
+
+  it('takes a number as readily as a string', () => {
+    expect(isolate(42)).toBe(`${FSI}42${PDI}`)
+  })
+
+  it('isolates every value of a bag, so a parameter added later is covered by construction', () => {
+    expect(isolated({ actor: 'Ada', person: 'Bruno' })).toEqual({
+      actor: `${FSI}Ada${PDI}`,
+      person: `${FSI}Bruno${PDI}`,
+    })
+  })
+})
+
+// ---------------------------------------------------------------- every call site, mechanically
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+/** Comments only. Never a code line, so a `//` inside a string literal cannot truncate a call. */
+function stripComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .split('\n')
+    .filter((line) => {
+      const trimmed = line.trimStart()
+      return !trimmed.startsWith('//') && !trimmed.startsWith('*')
+    })
+    .join('\n')
+}
+
+/**
+ * The arguments of a call, split on the commas that are actually arguments.
+ *
+ * **String-aware**, because a message key is not the only thing that can carry a comma and a
+ * scanner that silently finds fewer call sites than there are is one that passes while the defect
+ * ships. `errors.test.ts` has the same walker for the same reason.
+ */
+function argumentsOf(source: string, open: number): string[] | null {
+  const parts: string[] = []
+  let depth = 0
+  let quote: string | null = null
+  let start = open + 1
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i]
+    if (quote) {
+      if (ch === '\\') i++
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === '`') quote = ch
+    else if (ch === '(' || ch === '{' || ch === '[') depth++
+    else if (ch === ')' || ch === '}' || ch === ']') {
+      depth--
+      if (depth === 0) {
+        parts.push(source.slice(start, i))
+        return parts
+      }
+    } else if (ch === ',' && depth === 1) {
+      parts.push(source.slice(start, i))
+      start = i + 1
+    }
+  }
+  return null
+}
+
+/** The second argument of every `t(…)` call that has one. */
+function parameterisedCalls(source: string): Array<{ key: string; params: string }> {
+  const found: Array<{ key: string; params: string }> = []
+  for (const match of source.matchAll(/\bt\(/g)) {
+    const args = argumentsOf(source, match.index + match[0].length - 1)
+    if (!args || args.length < 2) continue
+    found.push({ key: args[0]!.trim(), params: args.slice(1).join(',').trim() })
+  }
+  return found
+}
+
+/**
+ * A count is exempt, and must be: `t()` formats a number through `Intl.NumberFormat`, so «۱۲»
+ * reaches a Persian reader as their own digits. Isolating it would hand `t()` a string instead and
+ * print "12" in the middle of a Persian sentence — the opposite of the fix.
+ */
+const COUNT_ONLY = /^\{\s*(n|count)\s*(:[^,}]+)?\s*\}$/
+
+function sources(): Array<{ file: string; text: string }> {
+  return readdirSync(HERE, { recursive: true, encoding: 'utf8' })
+    .filter((file) => (file.endsWith('.ts') || file.endsWith('.svelte')) && !file.endsWith('.test.ts'))
+    .map((file) => ({ file, text: stripComments(readFileSync(join(HERE, file), 'utf8')) }))
+}
+
+describe('every translated sentence isolates the values put into it', () => {
+  it('passes `isolated(…)` at every parameterised call site, or a bare count', () => {
+    const offenders: string[] = []
+    for (const { file, text } of sources())
+      for (const { key, params } of parameterisedCalls(text))
+        if (!params.startsWith('isolated(') && !COUNT_ONLY.test(params))
+          offenders.push(`${file}: t(${key}, ${params.replace(/\s+/g, ' ')})`)
+    expect(offenders).toEqual([])
+  })
+
+  /**
+   * The scanner has to actually find things, or an empty result would pass for ever. This module
+   * has dozens of parameterised messages; a run that finds none means the matcher broke, not that
+   * the code got better.
+   */
+  it('is looking at real call sites rather than passing on an empty sweep', () => {
+    const total = sources().reduce((sum, { text }) => sum + parameterisedCalls(text).length, 0)
+    expect(total).toBeGreaterThan(20)
+  })
+})

package/src/client/bidi.ts

@@ -0,0 +1,85 @@
+/**
+ * Putting a value somebody typed inside a sentence somebody else translated.
+ *
+ * **A Latin value dropped into a Persian or Arabic sentence renders backwards, and nothing about
+ * the source says so.** The Unicode bidirectional algorithm resolves the *neutral* characters at a
+ * run's edges — a quote, a bracket, a full stop, a hyphen — against the paragraph, not against the
+ * value they were typed as part of. So in an RTL paragraph:
+ *
+ * ```
+ * MacBook Pro 14" به Bruno Weber تحویل داده شد   →   … ﻪﺑ "MacBook Pro 14
+ * یادداشت: For the Berlin trip.                  →   .For the Berlin trip :ﺖﺷﺍﺩﺩﺎﯾ
+ * ```
+ *
+ * The inch mark leaves the name it belongs to and lands against the next word; the full stop of an
+ * English note ends up at the head of it. Both were reproduced with `fribidi` against this module's
+ * own catalogue before this file existed — an asset tag, a serial number and a Latin name inside
+ * `history_changed`, `held_by` and every `{name}` toast.
+ *
+ * `isolate()` is the fix the standard provides: **U+2068 FIRST STRONG ISOLATE** opens a run whose
+ * direction is taken from the value's own first strong character, and **U+2069 POP DIRECTIONAL
+ * ISOLATE** closes it. Neutrals inside the run resolve against the value; the run as a whole is
+ * placed as one unit in the sentence. First-strong rather than a forced LTR, because a Persian
+ * asset name inside a Persian sentence must go on reading right-to-left — the value decides, which
+ * is the whole point.
+ *
+ * **Where CSS can do it instead, CSS does it.** A value rendered into its own element — an asset
+ * tag in a `<code>`, a serial in a `<span class="ltr">` — carries `unicode-bidi: isolate` and needs
+ * nothing from here. This is for the other case: `t('history_changed', { from, to })` returns one
+ * string with the values already substituted, and there is no element left to put a rule on.
+ *
+ * Pure, and a plain module rather than something inside a component, for the reason `price.ts` and
+ * `timeline.ts` are: a `.svelte` file drags a compiler behind it and cannot be unit-tested.
+ */
+
+/**
+ * Written as escapes, never as the characters themselves.
+ *
+ * These are invisible. A literal one in a source file is a character nobody can see in a diff, in
+ * a review, or in an editor — and `price.ts` already strips a class of them precisely because they
+ * ride along on pasted text without anybody noticing.
+ */
+/** U+2068 FIRST STRONG ISOLATE — direction taken from the value's own first strong character. */
+export const FSI = '\u2068'
+/** U+2069 POP DIRECTIONAL ISOLATE. */
+export const PDI = '\u2069'
+
+/**
+ * The isolates (U+2066–U+2069) and the embeddings and overrides (U+202A–U+202E).
+ *
+ * Deliberately **not** LRM and RLM (U+200E, U+200F). Those are marks rather than containers: they
+ * cannot be left unbalanced, and `Intl.DateTimeFormat` puts them inside an Arabic date on purpose —
+ * `14‏/03‏/2027` is CLDR's own output, and stripping them would break the date to fix nothing.
+ */
+const CONTROLS = /[\u2066-\u2069\u202a-\u202e]/g
+
+/**
+ * One value, safe to interpolate into a translated sentence.
+ *
+ * An empty or absent value comes back as an empty string rather than as two invisible characters:
+ * a placeholder nothing filled should leave no trace in the sentence, and `{name}` is very often
+ * `asset?.name ?? ''` at the call site.
+ *
+ * Anything the value already carries is stripped first. Controls arrive by being pasted out of an
+ * RTL document — the same reason `price.ts` strips them before parsing a number — and an unbalanced
+ * one inside an isolate would reorder the rest of the sentence rather than the rest of the value.
+ */
+export function isolate(value: string | number | null | undefined): string {
+  if (value === null || value === undefined) return ''
+  const text = String(value).replace(CONTROLS, '')
+  return text ? `${FSI}${text}${PDI}` : ''
+}
+
+/**
+ * Isolate every value of a parameter bag, for the common case of a whole `t()` call.
+ *
+ * `t(key, isolated({ actor, person }))` rather than four `isolate()` calls at the site, so a
+ * parameter added to a message later is isolated by construction instead of by remembering.
+ */
+export function isolated<K extends string>(
+  params: Record<K, string | number | null | undefined>,
+): Record<K, string> {
+  const out = {} as Record<K, string>
+  for (const key of Object.keys(params) as K[]) out[key] = isolate(params[key])
+  return out
+}