create-mithaq 0.1.1 → 0.2.1

package/template/templates/asas/src/ui-dashboard/versions.tsx

@@ -6,7 +6,6 @@
 import { useContext, useEffect, useMemo, useState } from 'react'
 import { same, type ClientField, type ComponentProps, type Row } from 'mithaq/admin'
 import { FormContext, useAccess, useClient, useKayan, useLocale, useRecord, useScreen } from 'mithaq/admin/react'
-import { empty } from '../audit-log/sink.ts'
 import {
   AlertDialog,
   AlertDialogAction,
@@ -24,11 +23,24 @@ import { Label } from '@/components/ui/label'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { Sheet, SheetClose, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet'
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
-import { blocksOf, cellFor, richTextPlainText } from '@/components/mithaq/cells.tsx'
-import { formatDate, labelFor, refusalKeyOf, titleOf, type FindApi, type FoundPage } from '@/components/mithaq/controls.tsx'
-import { endonym } from '@/components/mithaq/nav.tsx'
-import { CloseButton } from '@/components/mithaq/nodes.tsx'
-import { useRelationshipTitles } from '@/components/mithaq/relationship-cell.tsx'
+import { blocksOf, richTextPlainText } from 'mithaq-admin/rich-text-line.ts'
+import { cellFor, useComponents } from 'mithaq-admin/components.tsx'
+import type { FindApi, FoundPage } from 'mithaq-admin/control-props.ts'
+import { labelFor, titleOf } from 'mithaq-admin/copy.ts'
+import { formatDate } from 'mithaq-admin/format.tsx'
+import { doneWords } from 'mithaq-admin/form-rules.tsx'
+import { carry } from 'mithaq-admin/toast.tsx'
+import { refusalKeyOf } from 'mithaq-admin/refusal.ts'
+import { endonym } from 'mithaq-admin/locale-menu.ts'
+import { CloseButton } from 'mithaq-admin/record-frame.tsx'
+import { useRelationshipTitles } from 'mithaq-admin/relationship-cell.tsx'
+
+/**
+ * What a version's column draws as a dash: absent, `null`, an empty string or
+ * an empty list, as the audit log's activity panel reads it. Its own here, so a
+ * project without the audit log keeps its versions.
+ */
+const empty = (value: unknown) => value === undefined || value === null || value === '' || (Array.isArray(value) && !value.length)
 
 /** One version as `findVersions` answers it. */
 export type Version = {
@@ -257,6 +269,7 @@ function Compare({ version, versions, parent, onClose }: { version: Version; ver
     [kayans],
   )
   const titles = useRelationshipTitles({ fields: kayan.fields, docs: [version.version, from?.version ?? {}], context: { api, client: kayans, locale } })
+  const { cells } = useComponents()
   const copy = { t, locale }
   // A rich text value whole, a block to a line, where its list cell draws the
   // first block alone: a change further down would read as no change. A block the
@@ -265,7 +278,7 @@ function Compare({ version, versions, parent, onClose }: { version: Version; ver
   // as well as tinted, so the mark does not rest on colour alone.
   const drawn = (field: ClientField, value: unknown, other: unknown, mark: 'del' | 'ins') => {
     if (empty(value)) return '—'
-    if (field.kind !== 'richText') return cellFor(field)({ kayan, field, value, t, locale, titles })
+    if (field.kind !== 'richText') return cellFor({ cells, field })({ kayan, field, value, t, locale, titles })
     const blocks = changedBlocks({ side: value, other })
     // A value of images or empty blocks alone has no words, and reads as empty.
     if (!blocks.length) return '—'
@@ -301,6 +314,7 @@ function Compare({ version, versions, parent, onClose }: { version: Version; ver
       // since is refused 409 rather than burying it.
       const read = takes ? versions.find((one) => one.latest)?.version.updatedAt : undefined
       await client({ kayan: kayan.name, operation: 'restoreVersion', input: { id: version.id, ...(read !== undefined && { expectedUpdatedAt: read }) }, draft })
+      carry(doneWords({ kayan, copy: { t, locale }, operation: { name: 'restoreVersion' } }))
       window.location.reload()
     } catch (thrown) {
       setRestoring(false)
@@ -349,7 +363,7 @@ function Compare({ version, versions, parent, onClose }: { version: Version; ver
           ) : 'failed' in prior && !against ? (
             <p role="alert" className="text-destructive text-sm">{t('version.failed', 'The versions could not be read.')}</p>
           ) : !rows.length ? (
-            <p className="text-muted-foreground text-sm">{t('auditLog.none', 'No field you may read changed.')}</p>
+            <p className="text-muted-foreground text-sm">{t('version.noReadableChange', 'No field you may read changed.')}</p>
           ) : (
             <ul className="grid gap-3 text-sm">
               {/* Which side is which, over the two columns, since on a phone

package/template/templates/asas/src/ui-portal/courses-home.tsx

@@ -0,0 +1,96 @@
+// What `/portal` itself draws for the courses example, in the portal's own look: a greeting, the viewer's next
+// session, and a few courses on offer it holds no seat in yet. It is the asas's own, since a screen's root page is
+// drawn from the project, and draws with the courses feature's portal pieces.
+import { useSyncExternalStore } from 'react'
+import { CalendarDays, MapPin } from 'lucide-react'
+import { useQuery } from '@tanstack/react-query'
+import { useClient, useLocale, useScreen, useUser } from 'mithaq/admin/react'
+import { buttonVariants } from '@/components/ui/button'
+import { Skeleton } from '@/components/ui/skeleton'
+import { PortalShell, display } from '@asas/courses/portal/ui/shell.tsx'
+import { CardsLoading, Cover, CourseCard, ReadFailed, usePlace } from '@asas/courses/portal/ui/parts.tsx'
+import { byWhen, partOfDay, startsIn, whenOf } from '@asas/courses/portal/ui/rules.ts'
+import { catalogueOf, readSeats } from '@asas/courses/portal/ui/reads.ts'
+
+/** How many courses the home offers before its link to the rest. */
+const offered = 3
+
+/** The hour on the viewer's own clock, and none on the server, which knows neither the clock nor the zone. */
+const useHour = () => useSyncExternalStore(() => () => {}, () => new Date().getHours(), () => undefined)
+
+export function Home() {
+  const { locale, t } = useLocale()
+  const client = useClient()
+  const screen = useScreen()
+  const user = useUser()
+  const place = usePlace()
+  const hour = useHour()
+  const now = Date.now()
+  // The viewer's own seats, whoever it is: an instructor reads every seat, and its next session is still its own.
+  const mine = useQuery({
+    queryKey: ['portal-mine', user.id],
+    queryFn: () => readSeats({ client, maxLimit: screen.maxLimit, where: { student: { equals: user.id } } }),
+    enabled: !!user.id,
+  })
+  const catalogue = useQuery({ queryKey: ['portal-catalogue'], queryFn: () => catalogueOf({ client, maxLimit: screen.maxLimit, now }), staleTime: 30_000 })
+  const next = mine.data && byWhen(mine.data, now).upcoming[0]
+  const held = new Set(mine.data?.map((one) => String(one.course?.id)))
+  // A course the student may enroll itself in, with a session to come, and no seat of its own in it yet.
+  const open = catalogue.data?.courses.filter((course) => course.selfEnroll === true && !held.has(String(course.id)) && catalogue.data.next.has(String(course.id))).slice(0, offered)
+  // One sentence per locale, so each says the name where its grammar puts it.
+  const greeting = (hour === undefined ? t('portal.welcome', 'Welcome, {name}') : t(`portal.greeting.${partOfDay(hour)}`, 'Hello, {name}'))!.replace('{name}', () => user.name)
+  return (
+    <PortalShell
+      regions={{
+        header: <h1 className={`${display} text-3xl leading-tight sm:text-4xl`}>{greeting}</h1>,
+        main: (
+          <div data-dashboard="portal" className="grid gap-8">
+            {mine.isPending && user.id ? <Skeleton className="h-52 rounded-3xl" /> : next ? (
+              <section aria-labelledby="next" className="bg-primary text-primary-foreground grid overflow-hidden rounded-3xl md:grid-cols-[3fr_2fr]">
+                <div className="grid content-start gap-3.5 p-5 sm:p-8">
+                  <h2 id="next" className="text-sm opacity-85">{t('portal.yourNext', 'Your next session')}</h2>
+                  <p className={`${display} text-2xl leading-tight sm:text-3xl`}>{String(next.course?.title ?? '')}</p>
+                  <div className="grid gap-1.5 text-[15px]">
+                    <span className="flex items-center gap-2"><CalendarDays aria-hidden className="size-4.5 shrink-0" />{whenOf({ value: next.startsAt, locale })}</span>
+                    {place(next.session) ? <span className="flex items-center gap-2"><MapPin aria-hidden className="size-4.5 shrink-0" />{place(next.session)}</span> : null}
+                  </div>
+                  <div className="flex flex-wrap items-center justify-between gap-3 pt-1">
+                    <span className="text-sm opacity-85">{t('portal.startsIn', 'Starts {when}')!.replace('{when}', () => startsIn({ value: next.startsAt, now, locale }) ?? '')}</span>
+                    {next.course ? (
+                      <a href={`${screen.path}/courses/${encodeURIComponent(String(next.course.id))}`} className={buttonVariants({ variant: 'secondary', className: 'bg-card text-primary h-11 rounded-full px-5 font-semibold' })}>
+                        {t('portal.viewCourse', 'View course')}
+                      </a>
+                    ) : null}
+                  </div>
+                </div>
+                <Cover course={next.course} cover={next.cover} className="hidden h-full min-h-60 w-full md:block" />
+              </section>
+            ) : null}
+            <section aria-labelledby="join" className="grid gap-4">
+              <div className="flex items-baseline justify-between gap-3">
+                <h2 id="join" className={`${display} text-xl sm:text-2xl`}>{t('portal.canJoin', 'Courses you can join')}</h2>
+                <a href={`${screen.path}/courses`} className="text-primary text-[15px] font-medium underline-offset-4 hover:underline">{t('portal.seeAll', 'See all courses')}</a>
+              </div>
+              {catalogue.isError ? <ReadFailed retry={() => void catalogue.refetch()} /> : !open ? <CardsLoading /> : open.length ? (
+                <div className="grid grid-cols-[repeat(auto-fill,minmax(16rem,1fr))] gap-5">
+                  {open.map((course) => (
+                    <CourseCard
+                      key={String(course.id)}
+                      course={course}
+                      cover={catalogue.data!.covers.get(String(course.cover))}
+                      next={catalogue.data!.next.get(String(course.id))}
+                      tags={catalogue.data!.tags}
+                      href={`${screen.path}/courses/${encodeURIComponent(String(course.id))}`}
+                    />
+                  ))}
+                </div>
+              ) : (
+                <p className="text-muted-foreground text-sm">{t('portal.noneToJoin', 'No course has a session coming up just now.')}</p>
+              )}
+            </section>
+          </div>
+        ),
+      }}
+    />
+  )
+}

package/template/templates/asas/src/ui-portal/home.tsx

@@ -1,23 +1,19 @@
-// What `/portal` itself draws, inside the portal's top shell: a greeting, then
-// the dashboard home's figure card for each of the portal's two lists, with how
-// many rows of it the viewer may read and a link to it, the courses on offer
-// alone. A list the nav does not offer the viewer has no card, and a list whose
+// What `/portal` itself draws in a project without the courses example, whose
+// portal draws its own home: a greeting, then the dashboard home's figure card
+// for each list below, with how many rows of it the viewer may read and a link
+// to it. A list the nav does not offer the viewer has no card, and a list whose
 // count the viewer may not read, or whose count failed, shows a dash in place
 // of the figure.
 import type { ReactNode } from 'react'
-import { BookOpen, ClipboardList } from 'lucide-react'
 import type { LoaderTools, PageProps } from 'mithaq/admin'
 import { useLocale, useScreen, useUser } from 'mithaq/admin/react'
-import { KpiCard } from '../ui/kpi-card.tsx'
-import { ScreenNav, navLabel } from '../ui/screen-nav.tsx'
-import { PortalTopShell } from '../ui/top-shell.tsx'
-import { onOffer } from '../courses/ui/on-offer.ts'
+import { KpiCard } from '@asas/mithaq/ui/kpi-card.tsx'
+import { ScreenNav, navLabel } from '@asas/mithaq/ui/screen-nav.tsx'
+import { PortalTopShell } from '@asas/mithaq/ui/top-shell.tsx'
 
 /** The lists the home counts, each with its card's icon and the rows its list is held to. */
-const figures: readonly [kayan: string, icon: ReactNode, where?: object][] = [
-  ['courses', <BookOpen className="size-4" />, onOffer],
-  ['enrollments', <ClipboardList className="size-4" />],
-]
+// A list of the project's own goes here, as `['tags', <Tags className="size-4" />]`.
+const figures: readonly [kayan: string, icon: ReactNode, where?: object][] = []
 
 /**
  * How many rows of each list the viewer may count, read as the viewer, keyed

package/template/templates/features/audit-log/audit-log/audit-log.ts

@@ -0,0 +1,284 @@
+import { actorPermissions, count, defaultFields, defaultJsonMaxBytes, denied, find, findOne, invalid, type Ctx, type Held } from 'mithaq'
+import { defineKayan, rows, organization } from '@asas/mithaq'
+import { backofficeClosed } from '@asas/mithaq/roles/tenant-access.ts'
+import { auditLogName, type Change } from '@asas/mithaq/mithaq/audit-sink.ts'
+
+/** The kayan whose `find` this actor holds, which are the kayan whose entries it reads. */
+const heldKayans = (held: Exclude<Held, true | undefined>) =>
+  [...held].filter((key) => key.endsWith('.find') && !key.includes('.fields.')).map((key) => key.slice(0, -'.find'.length))
+
+/**
+ * The read the log's rows are ANDed with, so it narrows and never widens: an
+ * entry of a kayan the actor may not list is no entry it reads. An actor
+ * nothing grades reads none, which is the closed direction.
+ */
+const readableKayans = ({ user }: { user: unknown }) => {
+  const held = actorPermissions(user)
+  if (held === true) return true
+  const kayans = held ? heldKayans(held) : []
+  return kayans.length ? { kayan: { in: kayans } } : false
+}
+
+/**
+ * Whether this actor reads one column of the kayan an entry names. The access
+ * target grades every column of this project by its key.
+ */
+const readsField = (held: Held, kayan: string, field: string) => held === true || held?.has(`${kayan}.fields.${field}`) === true
+
+/**
+ * Whether this actor reads the provider's people, by the key of their `find`.
+ * A command's operating-system user is the one thing in the log that names a
+ * person no row of the people does, so only such a reader sees or asks for it.
+ */
+const readsPeople = (held: Held) => held === true || held?.has('user.find') === true
+
+/**
+ * What the sink writes for a command: the command, then the operating-system
+ * user in parentheses. The command is the shortest part before ` (`, so a user
+ * holding a parenthesis is never left in it.
+ */
+const commandActor = /^(.+?) \(.+\)$/
+
+/**
+ * The step after the read: each entry keeps the changes of the columns the
+ * actor may read and drops the rest whole, so a column it may not read shows
+ * neither value nor that it changed. The server does it rather than the page,
+ * because the log is read over HTTP as well as drawn.
+ */
+const visibleChanges = (ctx: Ctx): Ctx => {
+  const held = actorPermissions(ctx.actor)
+  const trim = (entry: unknown) => {
+    const changes = (entry as { changes?: unknown } | null)?.changes
+    if (!changes || typeof changes !== 'object') return entry
+    const { kayan, actor } = entry as { kayan: string; actor?: unknown }
+    const kept = Object.fromEntries(Object.entries(changes as Record<string, Change>).filter(([field]) => readsField(held, kayan, field)))
+    // A command's actor is the command alone to a reader of no people, its operating-system user blanked.
+    const named = !readsPeople(held) && typeof actor === 'string' ? { actor: commandActor.exec(actor)?.[1] ?? actor } : {}
+    return { ...(entry as object), ...named, changes: kept }
+  }
+  const data: unknown = ctx.data
+  const page = data && typeof data === 'object' && Array.isArray((data as { docs?: unknown }).docs) ? (data as { docs: unknown[] }) : undefined
+  return { ...ctx, data: (page ? { ...page, docs: page.docs.map(trim) } : trim(data)) as Record<string, unknown> }
+}
+
+/**
+ * The columns the log is filtered and ordered by. The organization is core's
+ * own filter and `impersonatedBy` names staff.
+ */
+const queryable = new Set(['kayan', 'record', 'createdAt', 'operation', 'actor'])
+
+/**
+ * What the log is searched by besides those, never ordered by: `changes`, the
+ * whole of each change, or a path into it, `changes.<column>` and deeper. Each
+ * search takes any of the json kind's operators and reaches only the kayan whose
+ * columns it may tell of (`reachOf`), because a match in a column the reader
+ * holds no key for would say what that column held before `visibleChanges`
+ * trims the page.
+ */
+const searched = 'changes'
+
+/** The field a `where` key names: `changes.title.to` names `changes`. */
+const fieldOf = (key: string) => key.split('.')[0]!
+
+const namedIn = (where: unknown): string[] => {
+  if (!where || typeof where !== 'object') return []
+  return Object.entries(where).flatMap(([key, value]) =>
+    (key === 'and' || key === 'or') && Array.isArray(value) ? value.flatMap(namedIn) : [key])
+}
+
+/** Every column key the catalog holds, by the kayan it belongs to. */
+const columnsOf = (catalog: readonly string[]) => {
+  const columns = new Map<string, string[]>()
+  for (const key of catalog) {
+    const at = key.indexOf('.fields.')
+    if (at > 0) columns.set(key.slice(0, at), [...(columns.get(key.slice(0, at)) ?? []), key])
+  }
+  return columns
+}
+
+// ponytail: the reach here and `visibleChanges` grade by keys alone. A tenant role that a row
+// table narrows further, by a `fields` list or a row filter on its read, would be told of columns
+// and rows its own reads hide; grade each entry through the kayan's own field access and read
+// `where` before a project adds one.
+/**
+ * The kayan one search of a change reaches for this actor, or `true` for every
+ * one. The whole change reaches a kayan whose every column the actor reads, since
+ * it matches any of them; a path into one column, `changes.<column>`, a kayan
+ * whose column of that name it reads, since it matches inside that column alone.
+ */
+const reachOf = ({ held, catalog }: { held: Held; catalog: readonly string[] }) => (key: string): true | string[] => {
+  if (held === true) return true
+  const column = key.split('.')[1]
+  return [...columnsOf(catalog)]
+    .filter(([kayan, keys]) => held?.has(`${kayan}.find`) && (column === undefined ? keys.every((one) => held.has(one)) : held.has(`${kayan}.fields.${column}`)))
+    .map(([kayan]) => kayan)
+}
+
+/**
+ * The `where` with each search of a change ANDed, where it stands, with the kayan
+ * it reaches, so an `or` around it still means what it said, and a negation, a
+ * `not_equals` or an `exists: false`, still answers no entry past its reach.
+ */
+const narrowed = (where: unknown, reach: (key: string) => true | string[]): unknown => {
+  if (!where || typeof where !== 'object') return where
+  const parts = Object.entries(where).map(([key, value]) => {
+    if ((key === 'and' || key === 'or') && Array.isArray(value)) return { [key]: value.map((one) => narrowed(one, reach)) }
+    if (fieldOf(key) !== searched) return { [key]: value }
+    const kayans = reach(key)
+    return kayans === true ? { [key]: value } : { and: [{ [key]: value }, { kayan: { in: kayans } }] }
+  })
+  return parts.length === 1 ? parts[0] : { and: parts }
+}
+
+/**
+ * The step before the read: a `where` naming any column but those above, or a
+ * `sort` by any but the queryable ones, is refused 400 before the store is
+ * asked, on every read the log declares, and each search of a change is narrowed
+ * to the kayan it reaches. The runner's own checks still run after it on what it
+ * lets through.
+ */
+const queriedByQueryable = (ctx: Ctx, tools: { catalog: readonly string[] }): Ctx => {
+  // The runner names the organization a read is scoped to only where the read is not widened.
+  // `reachOf` and `visibleChanges` grade by the active organization's keys, so a read across every
+  // membership (`tenant: 'mine'`) would grade another organization's entries by this one's: it is
+  // refused before anything else of it is judged.
+  if (ctx.tenant === undefined) {
+    throw denied({ message: 'Kayan "auditLog" is read in the active organization alone.', key: 'error.forbidden.read', params: {} })
+  }
+  const { where, sort } = ctx.data as { where?: unknown; sort?: unknown }
+  const field = namedIn(where).find((name) => !queryable.has(name) && fieldOf(name) !== searched)
+  if (field !== undefined) {
+    throw invalid({ message: `Kayan "auditLog" is filtered by ${[...queryable, searched].join(', ')} alone, and not by "${field}".`, key: 'error.invalid.where', params: { kayan: 'auditLog', field } })
+  }
+  const held = actorPermissions(ctx.actor)
+  // A reader of no people names an actor in no filter and no sort: a pattern, a range, an order or
+  // even an equality over the string would let it confirm a guessed operating-system user of a
+  // command's actor.
+  if (!readsPeople(held) && (namedIn(where).includes('actor') || (typeof sort === 'string' && sort.replace(/^-/, '') === 'actor'))) {
+    throw invalid({ message: 'Kayan "auditLog" is neither filtered nor sorted by "actor" for a reader of no people.', key: 'error.invalid.where', params: { kayan: 'auditLog', field: 'actor' } })
+  }
+  if (sort !== undefined && !(typeof sort === 'string' && queryable.has(sort.replace(/^-/, '')))) {
+    throw invalid({ message: `Kayan "auditLog" is sorted by ${[...queryable].join(', ')} alone.`, key: 'error.invalid.sort_field', params: { kayan: 'auditLog', field: String(sort) } })
+  }
+  return where === undefined ? ctx : { ...ctx, data: { ...ctx.data, where: narrowed(where, reachOf({ held, catalog: tools.catalog })) } }
+}
+
+/**
+ * The audit log's rows: an organization reads its own entries, and nothing writes
+ * one through the log, a caller of any role included, since the service
+ * target's sink writes each entry through the store inside the write it
+ * records. Every backoffice role is closed: the backoffice lists no entry, and a
+ * staff member's own impersonated writes are the entries it would read.
+ */
+const auditLogAccess = rows({
+  '*': { create: false, read: true, update: false, delete: false },
+  ...backofficeClosed,
+})
+
+/**
+ * The audit log: one row per row a write changed, written by the service
+ * target's audit sink inside that write's own transaction and by nothing else.
+ * It declares no operation that writes, so no caller creates, edits or deletes
+ * an entry, and each of its rows answers `false` for every write besides.
+ *
+ * It is its organization's own. A record's last entries are read in its edit
+ * page's side column, all of them in its Activity tab, and the organization's on
+ * the dashboard's Activity page, a page of the screen's own rather than of this
+ * kayan, which draws none. The backoffice lists none of it and reads none of
+ * it: staff's own actions are its staff history, `backofficeLog`.
+ */
+export const auditLog = defineKayan({
+  name: auditLogName,
+  dbName: 'audit_log',
+  messages: {
+    singular: { en: 'Audit entry', ar: 'سجل تدقيق' },
+    plural: { en: 'Audit log', ar: 'سجل التدقيق' },
+    // What the activity panel draws beside the field labels.
+    activity: { en: 'Activity', ar: 'النشاط' },
+    loading: { en: 'Loading activity…', ar: 'جارٍ تحميل النشاط…' },
+    empty: { en: 'Nothing has changed here yet.', ar: 'لم يتغير شيء هنا بعد.' },
+    failed: { en: 'The activity could not be read.', ar: 'تعذرت قراءة النشاط.' },
+    more: { en: 'Show older', ar: 'عرض الأقدم' },
+    system: { en: 'The system', ar: 'النظام' },
+    event: { en: '{action} by {actor}', ar: '{action} بواسطة {actor}' },
+    // Staff writing as a member: the real person first, as the member they wrote as.
+    impersonated: { en: '{staff} as {member}', ar: '{staff} بصفة {member}' },
+    // One per operation a tenant kayan writes through, which is every entry the sink records.
+    action: {
+      create: { en: 'Created', ar: 'أُنشئ' },
+      update: { en: 'Updated', ar: 'حُدِّث' },
+      delete: { en: 'Deleted', ar: 'حُذف' },
+      updateMany: { en: 'Updated', ar: 'حُدِّث' },
+      deleteMany: { en: 'Deleted', ar: 'حُذف' },
+      restoreVersion: { en: 'Restored a version', ar: 'استُعيد إصدار' },
+      archive: { en: 'Archived', ar: 'أُرشف' },
+      archiveMany: { en: 'Archived', ar: 'أُرشف' },
+      unarchive: { en: 'Unarchived', ar: 'أُلغيت أرشفته' },
+      unpublish: { en: 'Unpublished', ar: 'أُلغي نشره' },
+      // An update that published a draft, which the sink names apart from a plain update.
+      publish: { en: 'Published', ar: 'نُشر' },
+    },
+    someone: { en: 'Someone', ar: 'شخص ما' },
+    // A command line write, named for a reader of the people: the command and
+    // the operating-system user who ran it.
+    command: { en: 'the command {command} ({user})', ar: 'الأمر {command} ({user})' },
+    // The viewer's own entry, which needs no read of the people to name. Its
+    // sentence is its own, since Arabic joins the person to "by" in one word,
+    // "بواسطتك", and not as "بواسطة أنت".
+    you: { en: 'You', ar: 'أنت' },
+    eventYou: { en: '{action} by You', ar: '{action} بواسطتك' },
+    none: { en: 'No field you may read changed.', ar: 'لم يتغير حقل يمكنك قراءته.' },
+    // Beside a change the sink cut to the start of its JSON, which a large json value is.
+    truncated: { en: 'Too long to keep whole; its start is shown.', ar: 'أطول من أن يُحفظ كاملا؛ تظهر بدايته.' },
+    // The panel's link to the rest of a record's entries, and the Activity page and tab.
+    all: { en: 'All activity', ar: 'كل النشاط' },
+    about: { en: 'Every change in this organization, newest first.', ar: 'كل تغيير في هذه المؤسسة، الأحدث أولا.' },
+    filters: { en: 'Filter the activity', ar: 'تصفية النشاط' },
+    // What the search box names as what it searches, in the sentence "Search changed values".
+    searchChanges: { en: 'changed values', ar: 'القيم المتغيرة' },
+    person: { en: 'Person', ar: 'الشخص' },
+    type: { en: 'Record type', ar: 'نوع السجل' },
+    field: { en: 'Field', ar: 'الحقل' },
+    actionFilter: { en: 'Action', ar: 'الإجراء' },
+    from: { en: 'From', ar: 'من' },
+    to: { en: 'To', ar: 'إلى' },
+    any: { en: 'Any', ar: 'الكل' },
+    filter: {
+      created: { en: 'Created', ar: 'أُنشئ' },
+      updated: { en: 'Updated', ar: 'حُدِّث' },
+      deleted: { en: 'Deleted', ar: 'حُذف' },
+      published: { en: 'Published', ar: 'نُشر' },
+      restored: { en: 'Restored', ar: 'استُعيد' },
+    },
+    clear: { en: 'Clear filters', ar: 'مسح عوامل التصفية' },
+    nothing: { en: 'No activity matches these filters.', ar: 'لا نشاط يطابق عوامل التصفية هذه.' },
+    oneRecord: { en: 'One record\'s activity.', ar: 'نشاط سجل واحد.' },
+    found: { en: 'Entries found: {count}', ar: 'السجلات المطابقة: {count}' },
+    searchLimited: { en: 'The search covers the records whose every field you may read.', ar: 'يشمل البحث السجلات التي يمكنك قراءة كل حقولها.' },
+  },
+  access: { ...auditLogAccess, read: readableKayans },
+  targets: {
+    dashboard: {},
+    service: {
+      operations: {
+        find: { steps: [queriedByQueryable, find, visibleChanges] },
+        findByID: { steps: [queriedByQueryable, findOne, visibleChanges] },
+        count: { steps: [queriedByQueryable, count] },
+      },
+    },
+  },
+  fields: {
+    id: defaultFields.id,
+    createdAt: defaultFields.createdAt,
+    organization,
+    kayan: { kind: 'text', label: { en: 'Kayan', ar: 'الكيان' }, rules: { required: true, maxLength: 60 } },
+    record: { kind: 'text', label: { en: 'Record', ar: 'السجل' }, rules: { required: true, index: true } },
+    operation: { kind: 'text', label: { en: 'Operation', ar: 'العملية' }, rules: { required: true, maxLength: 60 } },
+    actor: { kind: 'text', label: { en: 'Actor', ar: 'المنفذ' } },
+    impersonatedBy: { kind: 'text', label: { en: 'Impersonated by', ar: 'انتحل الصفة' } },
+    // Each changed column by name, so a search finds the change of one column by
+    // the path `changes.<column>`, which `queriedByQueryable` grades by that
+    // column's key. Never an order, as no json field is.
+    changes: { kind: 'json', label: { en: 'Changes', ar: 'التغييرات' }, maxBytes: defaultJsonMaxBytes, rules: { required: true } },
+  },
+})

package/template/templates/features/audit-log/backoffice-log/backoffice-log.ts

@@ -0,0 +1,67 @@
+import { defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan, rows } from '@asas/mithaq'
+import { backofficeList } from '@asas/mithaq/mithaq/pages.ts'
+import { backofficeReads } from '@asas/mithaq/roles/tenant-access.ts'
+
+/** Who did what to whom on the backoffice, as `action` names it. */
+const actions = [
+  { value: 'impersonate', label: { en: 'Started impersonating', ar: 'بدأ انتحال الصفة' } },
+  { value: 'stopImpersonating', label: { en: 'Stopped impersonating', ar: 'أنهى انتحال الصفة' } },
+  { value: 'setRole', label: { en: 'Set the backoffice role', ar: 'عيّن دور الإدارة الخلفية' } },
+  { value: 'ban', label: { en: 'Banned', ar: 'حظر' } },
+  { value: 'unban', label: { en: 'Lifted the ban', ar: 'رفع الحظر' } },
+] as const
+
+const text = (label: { en: string; ar: string }) => ({ kind: 'text', label }) as const
+
+/**
+ * The staff history: one row per impersonation started or stopped, backoffice
+ * role set and ban set or lifted, written by the auth setup's backoffice hook
+ * once the provider's route succeeded, and by nothing else. It belongs to no
+ * organization, since staff act above every tenant, and it declares no
+ * operation that writes, so no caller makes, edits or removes a row.
+ *
+ * Only a backoffice role reads it, in the backoffice app alone, and only one
+ * holding its keys: the row table names no `'*'` row, so a tenant's
+ * administrator, who holds every key of the project, takes no row of it and is
+ * refused. The tenant app's screens list none of it.
+ *
+ * Each person is kept by id and by the address they had then, so the history
+ * still says who once a person is renamed or removed.
+ */
+export const backofficeLog = defineKayan({
+  name: 'backofficeLog',
+  dbName: 'backoffice_log',
+  messages: {
+    singular: { en: 'Staff action', ar: 'إجراء طاقم' },
+    plural: { en: 'Staff history', ar: 'سجل الطاقم' },
+  },
+  access: rows({ ...backofficeReads }),
+  targets: {
+    service: {
+      operations: { find: defaultOperations.find, findByID: defaultOperations.findByID, count: defaultOperations.count },
+    },
+    backoffice: {
+      pages: {
+        ...backofficeList('/history', {
+          columns: ['createdAt', 'action', 'actorEmail', 'targetEmail', 'previousRole', 'role', 'banReason'],
+          filters: ['action', 'actorEmail', 'targetEmail', 'createdAt'],
+          search: ['actorEmail', 'targetEmail'],
+          sort: '-createdAt',
+        }),
+      },
+    },
+  },
+  fields: {
+    id: defaultFields.id,
+    createdAt: defaultFields.createdAt,
+    action: { kind: 'text', label: { en: 'Action', ar: 'الإجراء' }, options: actions, rules: { required: true } },
+    actor: text({ en: 'Staff member', ar: 'عضو الطاقم' }),
+    actorEmail: text({ en: 'Staff member\'s email', ar: 'بريد عضو الطاقم' }),
+    target: text({ en: 'Person', ar: 'الشخص' }),
+    targetEmail: text({ en: 'Person\'s email', ar: 'بريد الشخص' }),
+    previousRole: text({ en: 'Role before', ar: 'الدور السابق' }),
+    role: text({ en: 'Role after', ar: 'الدور الجديد' }),
+    banReason: text({ en: 'Ban reason', ar: 'سبب الحظر' }),
+  },
+})

package/template/templates/features/audit-log/index.ts

@@ -0,0 +1,4 @@
+import { auditLog } from './audit-log/audit-log.ts'
+import { backofficeLog } from './backoffice-log/backoffice-log.ts'
+
+export const kayan = [auditLog, backofficeLog] as const

package/template/templates/features/audit-log/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@asas/audit-log",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "mithaq": "*"
+  }
+}

package/template/templates/features/auth/index.ts

@@ -0,0 +1,11 @@
+import { localUsers } from './local-users/local-users.ts'
+// Written by `mithaq generate auth`: one key per plugin the vocabulary names,
+// and `core` for the four Better Auth ships without one. Spreading the keys is
+// what keeps this list from naming eight files, and a project that drops the
+// organization plugin drops one spread.
+import { betterAuth } from './user/index.ts'
+
+// The account other features point at, and the asas names its administrator by.
+export { user } from './user/user.ts'
+
+export const kayan = [...betterAuth.core, ...betterAuth.organization, localUsers] as const

package/template/templates/{asas/src → features/auth}/local-users/local-users.ts

@@ -9,9 +9,9 @@ import {
   defaultOperations,
   type Ctx,
 } from 'mithaq'
-import { defineKayan, requestContext } from '../mithaq.ts'
-import { appPage, platformList } from '../pages.ts'
-import { superAdmin } from '../tenant-access.ts'
+import { defineKayan, requestContext } from '@asas/mithaq'
+import { appPage, backofficeList } from '@asas/mithaq/mithaq/pages.ts'
+import { superAdmin } from '@asas/mithaq/roles/tenant-access.ts'
 
 /**
  * The trusted-header names this deployment's own proxy overwrites with the real client address, read
@@ -62,7 +62,7 @@ export const localUsers = defineKayan({
   // would share one count; there, take the entry at the depth of the trusted proxies. A project served
   // bare passes its server's own address instead, such as Bun's `server.requestIP(request)`. No header
   // answers null, which leaves the request uncounted.
-  // No `email` is passed, so no mail is sent: a super admin verifies each sign-up in the platform app.
+  // No `email` is passed, so no mail is sent: a super admin verifies each sign-up in the backoffice app.
   auth: local({
     secret,
     withoutSecret: 'Local sign-in is off on this server: LOCAL_AUTH_SECRET is not set. Set it to a secret of 32 characters at least and restart the server.',
@@ -91,10 +91,10 @@ export const localUsers = defineKayan({
      * The form sends only what changed, so an unchanged toggle writes nothing and leaves `updatedAt`
      * alone. The protected columns are named by no page, so no list offers one as a column or a filter.
      */
-    platform: {
+    backoffice: {
       useAsTitle: 'email',
       pages: {
-        ...platformList('/local-users', {
+        ...backofficeList('/local-users', {
           columns: ['email', '_verified', 'createdAt'],
           filters: ['_verified'],
           search: ['email'],
@@ -121,7 +121,7 @@ export const localUsers = defineKayan({
       },
     },
   },
-  // Public sign-up stays open. A super admin, in the platform app alone, verifies an account by writing
+  // Public sign-up stays open. A super admin, in the backoffice app alone, verifies an account by writing
   // `_verified: true`, which the field's own write admits from the administrator and nobody else. The
   // super admin writes `_verified` and nothing else: a password or an email it set would be an account
   // it could then log in as, and no audit entry records a write to a kayan with no tenant. An