create-mithaq 0.0.0-stage → 0.1.1

package/template/templates/asas/src/kayan/auth/user/user.screens.ts

@@ -0,0 +1,45 @@
+// What each screen draws of the generated `user` kayan, which `mithaq generate
+// auth` imports into `./user.ts` because this file sits beside it, spreading it
+// into the kayan's `targets` after the generated titles of the screens it does
+// not name, so the platform's block here is that screen's whole block, its
+// title included, and the dashboard keeps the generated one. The dashboard
+// titles a person by name for its cells and pickers, and the platform lists
+// every person with the registry's list and acts on each from its row's menu
+// and its own page.
+import { platformUi } from '../../../mithaq.ts'
+import { appPage } from '../../../pages.ts'
+
+export const screens = {
+  platform: {
+    useAsTitle: 'name',
+    pages: {
+      list: {
+        path: '/users',
+        page: appPage([{ layout: 'table', main: [{ list: {
+          columns: ['name', 'email', { field: 'role', cell: platformUi('user-actions.tsx#PlatformRole') }, 'banned', 'createdAt'],
+          filters: ['name', 'email', 'role', 'banned', 'createdAt'],
+          search: ['name', 'email'],
+          sort: 'email',
+          // Set role, ban and impersonate, after the row menu's View.
+          menu: platformUi('user-actions.tsx#UserMenu'),
+        } }] }]),
+      },
+      // A person's record, which a row opens and which only reads: every
+      // column drawn by its cell, under the actions the row's menu offers, as buttons.
+      view: {
+        path: '/users/:id',
+        page: appPage([{
+          layout: 'record',
+          main: [
+            { component: platformUi('user-actions.tsx#UserButtons') },
+            { section: 'person', label: { en: 'Person', ar: 'الشخص' }, fields: ['name', 'email', 'emailVerified', 'image'] },
+            // The role by its label, where the column holds the slugs.
+            { section: 'standing', label: { en: 'Standing on the platform', ar: 'الوضع في المنصة' }, fields: [{ field: 'role', cell: platformUi('user-actions.tsx#PlatformRole') }, 'banned', 'banReason', 'banExpires'] },
+          ],
+          // No id: a person reads the record by its name, and the address bar holds the id.
+          side: [{ section: 'record', label: { en: 'Record', ar: 'السجل' }, fields: ['createdAt', 'updatedAt'] }],
+        }]),
+      },
+    },
+  },
+} as const

package/template/templates/asas/src/kayan/auth/user/user.ts

@@ -0,0 +1,31 @@
+// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.
+// This kayan's access and what each screen draws of it are the project's:
+// `user.access.ts` exporting `access` and `user.screens.ts` exporting
+// `screens`, beside this file, are imported here on the next run. A kayan
+// built under this one's name elsewhere is refused by every relationship to it.
+import { betterAuth, defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan } from '../../../mithaq.ts'
+import { providers } from '@asas/auth'
+import { access } from './user.access.ts'
+import { screens } from './user.screens.ts'
+
+export const user = defineKayan({
+  name: 'user',
+  auth: betterAuth({ server: providers.user.server }),
+  targets: { dashboard: { useAsTitle: 'name' }, portal: { useAsTitle: 'name' }, ...screens, service: { operations: defaultOperations } },
+  access,
+  fields: {
+    ...defaultFields,
+    id: { kind: 'text' },
+    name: { kind: 'text', rules: { required: true } },
+    email: { kind: 'text', rules: { required: true, unique: true } },
+    emailVerified: { kind: 'checkbox', rules: { required: true } },
+    image: { kind: 'text' },
+    createdAt: { kind: 'datetime', rules: { required: true } },
+    updatedAt: { kind: 'datetime', rules: { required: true, nowOnUpdate: true, providedBy: { update: 'application' } } },
+    role: { kind: 'text' },
+    banned: { kind: 'checkbox' },
+    banReason: { kind: 'text' },
+    banExpires: { kind: 'datetime' },
+  },
+})

package/template/templates/asas/src/kayan/auth/user/verification.access.ts

@@ -0,0 +1,8 @@
+// This project's access for the generated `verification` kayan, which `mithaq generate
+// auth` imports into `./verification.ts` because this file sits beside it.
+//
+// Better Auth alone writes and reads this table, through its own adapter, so
+// every managed operation on it is refused to every actor. Written out rather
+// than left to the administrator's default, which a super admin passes in the
+// platform app.
+export { providerOnly as access } from '../../../tenant-access.ts'

package/template/templates/asas/src/kayan/auth/user/verification.ts

@@ -0,0 +1,23 @@
+// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.
+// This kayan's access and what each screen draws of it are the project's:
+// `verification.access.ts` exporting `access` and `verification.screens.ts` exporting
+// `screens`, beside this file, are imported here on the next run. A kayan
+// built under this one's name elsewhere is refused by every relationship to it.
+import { defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan } from '../../../mithaq.ts'
+import { access } from './verification.access.ts'
+
+export const verification = defineKayan({
+  name: 'verification',
+  targets: { service: { operations: defaultOperations } },
+  access,
+  fields: {
+    ...defaultFields,
+    id: { kind: 'text' },
+    identifier: { kind: 'text', rules: { required: true } },
+    value: { kind: 'text', rules: { required: true } },
+    expiresAt: { kind: 'datetime', rules: { required: true } },
+    createdAt: { kind: 'datetime', rules: { required: true } },
+    updatedAt: { kind: 'datetime', rules: { required: true, nowOnUpdate: true, providedBy: { update: 'application' } } },
+  },
+})

package/template/templates/asas/src/local-users/local-users.ts

@@ -0,0 +1,143 @@
+import {
+  defaultFields,
+  defaultLockTime,
+  defaultMaxLoginAttempts,
+  defaultTokenExpiration,
+  local,
+  localAuthFields,
+  localAuthOperations,
+  defaultOperations,
+  type Ctx,
+} from 'mithaq'
+import { defineKayan, requestContext } from '../mithaq.ts'
+import { appPage, platformList } from '../pages.ts'
+import { superAdmin } from '../tenant-access.ts'
+
+/**
+ * The trusted-header names this deployment's own proxy overwrites with the real client address, read
+ * from the same `TRUSTED_IP_HEADER` variable Better Auth's `advanced.ipAddress.ipAddressHeaders` is
+ * fed from, so both limiters key on the same address. Unset, it falls back to `x-forwarded-for`.
+ */
+export const ip = (request: Request): string | null => {
+  const headers = process.env.TRUSTED_IP_HEADER?.split(',').map((header) => header.trim()).filter(Boolean) ?? [
+    'x-forwarded-for',
+  ]
+  for (const header of headers) {
+    const value = request.headers.get(header)?.split(',').at(-1)?.trim()
+    if (value) return value
+  }
+  return null
+}
+
+/**
+ * The secret local auth signs its tokens with, 32 characters at least, from the environment and
+ * never from this file: a secret written here is one anyone reading the repository forges a token
+ * with. Unset or empty, local auth is off as a whole: every POST to `/api/auth/local` answers
+ * `withoutSecret` below with a 503, and the public sign-up with a 403. The kayan keeps its provider,
+ * fields and operations, so the build and every file generated from it are the same in every
+ * environment.
+ */
+const secret = process.env.LOCAL_AUTH_SECRET || undefined
+
+const markVerified = (ctx: Ctx): Ctx => ({ ...ctx, data: { ...ctx.data, _verified: true } })
+
+/**
+ * The kayan the local auth provider writes. It spreads the shipped `localAuthFields` and
+ * `localAuthOperations`, so every column and step it has is written here, and the build refuses a
+ * protected column left readable.
+ */
+export const localUsers = defineKayan({
+  name: 'localUsers',
+  dbName: 'local_users',
+  messages: {
+    singular: { en: 'Local account', ar: 'حساب محلي' },
+    plural: { en: 'Local accounts', ar: 'الحسابات المحلية' },
+  },
+  // `context` is what first registration hands its steps.
+  //
+  // `ip` reads the last entry of whichever header `TRUSTED_IP_HEADER` names, the one the trusted proxy
+  // in front of it appended, because no host this template is served by hands the socket address to
+  // the `Request`. That is only safe behind exactly one such proxy: without one any caller writes the
+  // header, and behind more than one the last entry is the nearest proxy's own address, so every user
+  // 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.
+  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.',
+    context: requestContext,
+    ip,
+    tokenExpiration: defaultTokenExpiration,
+    maxLoginAttempts: defaultMaxLoginAttempts,
+    lockTime: defaultLockTime,
+  }),
+  targets: {
+    service: {
+      operations: {
+        ...defaultOperations,
+        ...localAuthOperations,
+        // The provider's own update with one step before it that writes `_verified: true` over whatever
+        // the call sent, so it can only verify; the access below judges it as an update with that one key
+        // as its data.
+        verify: { ...localAuthOperations.update, steps: [markVerified, ...localAuthOperations.update.steps] },
+      },
+    },
+    /**
+     * Where a super admin verifies a sign-up: the accounts by email, verified state and the date each
+     * was made, and an edit page whose form is the verified toggle alone. Its fields are written here,
+     * never read off `/api/access`, which reports `update` for `email` because the kayan's own `update`
+     * asks the data and the report has none; the access above still refuses any write but `_verified`.
+     * 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: {
+      useAsTitle: 'email',
+      pages: {
+        ...platformList('/local-users', {
+          columns: ['email', '_verified', 'createdAt'],
+          filters: ['_verified'],
+          search: ['email'],
+          row: [{
+            button: 'verify',
+            when: { or: [{ 'record._verified': { exists: false } }, { 'record._verified': { equals: false } }] },
+            label: { en: 'Verify', ar: 'توثيق' },
+            confirm: {
+              title: { en: 'Verify this account?', ar: 'توثيق هذا الحساب؟' },
+              body: { en: 'Its owner can sign in from now on.', ar: 'يستطيع صاحبه تسجيل الدخول من الآن.' },
+            },
+          }],
+        }),
+        // Read-only above the toggle: a read-only leaf is drawn and never sent, so a save still writes
+        // `_verified` alone.
+        edit: {
+          path: '/local-users/:id',
+          page: appPage([{ layout: 'record', main: [{ form: [{ section: 'verification', label: { en: 'Verification', ar: 'التحقق' }, fields: [
+            { field: 'email', readOnly: true },
+            { field: 'createdAt', readOnly: true },
+            '_verified',
+          ] }] }] }]),
+        },
+      },
+    },
+  },
+  // Public sign-up stays open. A super admin, in the platform 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
+  // `updateMany` is asked this again for each row it writes, with that row's values. Everyone else, a
+  // local user on its own row included, reads and writes none.
+  access: {
+    create: () => true,
+    read: superAdmin,
+    update: ({ user, data }) => superAdmin({ user }) && Object.keys(data ?? {}).every((key) => key === '_verified'),
+    delete: () => false,
+  },
+  // A label leaves the shipped access in place, which the build compares by identity.
+  fields: {
+    ...defaultFields,
+    ...localAuthFields,
+    email: { ...localAuthFields.email, label: { en: 'Email', ar: 'البريد الإلكتروني' } },
+    _verified: { ...localAuthFields._verified, label: { en: 'Verified', ar: 'موثق' } },
+  },
+})

package/template/templates/asas/src/media/media.ts

@@ -0,0 +1,137 @@
+import { actorPermissions, defaultFields, defaultOperations, folderOf, uploadFields, withUploadReference, type Where } from 'mithaq'
+import { defineKayan, serverTargets, organization } from '../mithaq.ts'
+import { courses } from '../courses/courses.ts'
+import { currentOrganization, readsPast } from '../tenant-access.ts'
+import { appPage, danger } from '../pages.ts'
+import { storageConfig } from '../storage/index.ts'
+
+const ui = folderOf(new URL('./ui/', import.meta.url))
+
+/**
+ * The images an actor reads, inside its active organization: every image of
+ * its organization where it holds `media.create`, and otherwise only the cover
+ * of a course it reads. `media.create` is the line
+ * because a role that adds images has to find one before any course names it,
+ * in the cover's picker. So a student or an instructor reads no image of a
+ * draft, of an archived course or of none, through find, findByID and
+ * `GET /api/media/file/<id>`, and the administrator and the registrar read all of them.
+ *
+ * "A course it reads" is a published course of the organization the actor's session has
+ * active, read off the trusted snapshot, under the courses kayan's own read
+ * access for this actor. The courses are read straight through the store,
+ * past the runner's scope, so the organization is named here and the read
+ * never reaches past it whatever the access answers.
+ * An image has no field that points at a course, so a row filter cannot reach
+ * one, and the covers are read first and named by id.
+ */
+const coversOfReadableCourses = async ({ user }: { user: unknown }) => {
+  if (readsPast(user, 'media.create')) return true
+  const held = actorPermissions(user)
+  if (held !== true && !held?.has('courses.find')) return false
+  const active = currentOrganization(user)
+  const readable = active && (await courses.access!.read!({ user }))
+  if (!readable) return false
+  const published: Where = { and: [{ organization: { equals: active } }, { _status: { equals: 'published' } }] }
+  const found = await serverTargets.drizzle.find({ kayan: 'courses', args: {
+    limit: 0,
+    page: 1,
+    sort: { field: 'id', direction: 'asc' },
+    where: readable === true ? published : { and: [readable, published] },
+  } })
+  const ids = [...new Set(found.docs.map((row) => row.cover).filter((id): id is string => typeof id === 'string'))]
+  return ids.length ? { id: { in: ids } } : false
+}
+
+/**
+ * The organization's images: a row per file, whose object is kept where the
+ * project's storage puts it. A course points at one as its cover.
+ *
+ * It spreads `uploadFields`, the columns the create writes from the upload it
+ * verified and nobody writes after, and declares its own create and delete:
+ * the create takes the signed `uploadReference` that
+ * `POST /api/media/uploadInstructions` handed out and runs the project's
+ * `uploaded`, and the delete runs its `removed` after the commit. `buildAsas`
+ * refuses a create that skips the configured `uploaded`. A file is
+ * read at `GET /api/media/file/<id>` through this kayan's own `findByID`, so
+ * its organization and `coversOfReadableCourses` decide who reads it. It keeps no versions, since a file never changes once it is
+ * made; a course keeps the versions of its cover instead.
+ */
+export const media = defineKayan({
+  name: 'media',
+  // ANDed with the inherited rows, so it narrows and never widens.
+  access: { read: coversOfReadableCourses },
+  messages: {
+    singular: { en: 'Image', ar: 'صورة' },
+    plural: { en: 'Images', ar: 'الصور' },
+  },
+  targets: {
+    storage: { mimeTypes: ['image/png', 'image/jpeg', 'image/webp'] },
+    // A file is named by its name wherever it stands for itself: the upload
+    // control's picker and a relationship column pointing here.
+    portal: { useAsTitle: 'filename' },
+    // The organization's images, listed and re-described. A file is made
+    // where it is used, by the upload control, and on this kayan's own New
+    // page, both through the upload dialog, which sends it before the row is
+    // made. The list draws each image's thumbnail beside its name and its size as a
+    // person reads it. The file's own columns are the runner's, so the edit
+    // page draws them read-only, with the image, its size, Download and
+    // Replace file beside the form, and above it on a phone.
+    dashboard: {
+      useAsTitle: 'filename',
+      description: { en: 'The images this organization uses, each with the words a screen reader says for it.', ar: 'الصور التي تستخدمها هذه المؤسسة، ولكل منها الكلمات التي يقرؤها قارئ الشاشة.' },
+      pages: {
+        list: { path: '/media', page: appPage([{ layout: 'table', main: [{ list: {
+          columns: [{ field: 'filename', cell: ui('preview.tsx#FileName') }, 'alt', 'mimeType', { field: 'filesize', cell: ui('preview.tsx#FileSize') }, 'createdAt'],
+          search: ['filename'],
+          sort: '-createdAt',
+        } }] }]) },
+        create: { path: '/media/new', component: ui('preview.tsx#NewImage') },
+        edit: {
+          path: '/media/:id',
+          page: appPage([{
+            layout: 'record',
+            main: [{ form: [
+              { section: 'description', label: { en: 'Description', ar: 'الوصف' }, fields: ['alt'] },
+              { section: 'file', label: { en: 'File', ar: 'الملف' }, fields: ['filename', 'mimeType', { row: ['width', 'height'] }] },
+            ] }],
+            side: [{ component: ui('preview.tsx#MediaPreview') }],
+            danger: danger(),
+          }]),
+        },
+      },
+    },
+    service: {
+      operations: {
+        ...defaultOperations,
+        // The upload inside the create. Before the transaction opens, the
+        // signed reference is checked and the stored object is read back,
+        // and every file column is written from what the server measured.
+        // Then the row is made in one insert.
+        create: {
+          ...defaultOperations.create,
+          input: ({ create }) => withUploadReference(create),
+          beforeTransaction: [storageConfig.uploaded],
+        },
+        // The object is removed only once the row's removal has committed,
+        // so a failure leaves an orphan for the sweep and never a row that
+        // names nothing.
+        delete: {
+          ...defaultOperations.delete,
+          afterCommit: ({ afterCommit }) => [...afterCommit, storageConfig.removed],
+        },
+      },
+    },
+  },
+  fields: {
+    ...defaultFields,
+    organization,
+    ...uploadFields,
+    // What a screen reader says for the image, in every locale, since an
+    // image with no words is no image to someone who cannot see it.
+    alt: {
+      kind: 'text',
+      label: { en: 'Alternative text', ar: 'النص البديل' },
+      rules: { localized: true, required: true, maxLength: 300 },
+    },
+  },
+})

package/template/templates/asas/src/media/ui/preview.tsx

@@ -0,0 +1,143 @@
+// What the `media` kayan draws of its own files: the image beside its edit
+// form, the list's thumbnail and size cells, and the page a new image is made
+// on. Each reads the row's computed `url` and `thumbnailURL`, so a file is
+// fetched through the file route and the row's access decides. A new file is
+// made in the registry's upload dialog, which sends the bytes before the row
+// is made.
+import { useRef, useState } from 'react'
+import { Download, Upload } from 'lucide-react'
+import type { CellProps, ComponentProps, Row } from 'mithaq/admin'
+import { useAccess, useClient, useLocale, useRecord, useScreen } from 'mithaq/admin/react'
+import { locales } from '@/copy.ts'
+import { Button, buttonVariants } from '@/components/ui/button'
+import { FileThumb, FileValue, UploadDialog, sizeOf } from '@/components/mithaq/upload.tsx'
+import { AppShell } from '../../ui/app-shell.tsx'
+
+/** The `filesize` column: the size as a person reads it, never the raw bytes, in the upload dialog's own units. */
+export function FileSize({ value }: CellProps) {
+  const { locale } = useLocale()
+  return typeof value === 'number' ? <span className="whitespace-nowrap">{sizeOf(value, locale)}</span> : null
+}
+
+/**
+ * The `filename` column: the image's thumbnail before its name. The name
+ * keeps at least seven rem and wraps onto a second line before it is cut,
+ * between words where it has them and anywhere only where it must, so
+ * on a phone the table gives the column room for it rather than squeezing it
+ * to "co…" beside the thumbnail.
+ */
+export function FileName({ value, row }: CellProps) {
+  const { t, locale } = useLocale()
+  const name = String(value ?? '')
+  return (
+    <span className="inline-flex min-w-0 items-center gap-2">
+      <FileThumb row={row} t={t} locale={locale} size="xs" />
+      <span className="line-clamp-2 min-w-28 [overflow-wrap:anywhere]" dir="auto" title={name}>{name}</span>
+    </span>
+  )
+}
+
+const useEditHref = () => {
+  const { path, kayan } = useScreen()
+  return (id: unknown) => `${path}${kayan.media?.pages.edit?.path.replace(':id', encodeURIComponent(String(id)))}`
+}
+
+/** The upload dialog over this kayan, which opens the new image's page once it is made. */
+function NewImageDialog({ open, onOpenChange }: { open: boolean; onOpenChange: (open: boolean) => void }) {
+  const { t, locale } = useLocale()
+  const { kayan } = useScreen()
+  const client = useClient()
+  const editHref = useEditHref()
+  // The dialog closes itself once the row is made, and that close is no
+  // Cancel: the new image's page is already opening.
+  const done = useRef(false)
+  return kayan.media ? (
+    <UploadDialog
+      open={open}
+      onOpenChange={(next) => done.current || onOpenChange(next)}
+      target={kayan.media}
+      client={client}
+      t={t}
+      locale={locale}
+      locales={locales}
+      onDone={(row: Row) => {
+        done.current = true
+        window.location.assign(editHref(row.id))
+      }}
+    />
+  ) : null
+}
+
+/**
+ * The image beside its edit form, and above it on a phone, where the record
+ * layout puts a side marked `data-lead` first: the image itself, its size, a
+ * link that downloads it, and Replace file. A file never changes once it is
+ * made, so Replace file uploads a new image and opens it, and this one stays,
+ * with whatever points at it, until it is deleted.
+ */
+export function MediaPreview() {
+  const { t, locale } = useLocale()
+  const access = useAccess()
+  const row = useRecord()
+  const [replacing, setReplacing] = useState(false)
+  if (!row) return null
+  const creates = access.collections?.media?.create === true
+  const url = typeof row.url === 'string' ? row.url : undefined
+  return (
+    <div data-media-preview="" data-lead="" className="grid justify-items-start gap-3">
+      <FileValue row={row} t={t} locale={locale} />
+      {typeof row.filesize === 'number' ? <p className="text-muted-foreground text-sm">{sizeOf(row.filesize, locale)}</p> : null}
+      <div className="flex flex-wrap gap-2">
+        {url ? (
+          <a href={url} download={typeof row.filename === 'string' ? row.filename : ''} data-media-download="" className={buttonVariants({ variant: 'outline', size: 'sm' })}>
+            <Download className="size-4" aria-hidden />
+            {t('media.download', 'Download')}
+          </a>
+        ) : null}
+        {creates ? (
+          <Button type="button" variant="outline" size="sm" data-media-replace="" onClick={() => setReplacing(true)}>
+            <Upload className="size-4" aria-hidden />
+            {t('media.replace', 'Replace file')}
+          </Button>
+        ) : null}
+      </div>
+      {creates ? <p className="text-muted-foreground text-xs">{t('media.replaceAbout', 'Replace file uploads a new image and opens it. This one stays until you delete it.')}</p> : null}
+      <NewImageDialog open={replacing} onOpenChange={setReplacing} />
+    </div>
+  )
+}
+
+/**
+ * The New page, `/media/new`, which the list's New button opens: the upload
+ * dialog, open at once, and the page under it, which opens it again. Closing
+ * it goes back to the list.
+ */
+export function NewImage(_props: ComponentProps) {
+  const { t } = useLocale()
+  const { path, kayan } = useScreen()
+  const [open, setOpen] = useState(true)
+  const list = `${path}${kayan.media?.pages.list?.path ?? ''}`
+  return (
+    <AppShell
+      regions={{
+        header: <h1>{t('media.new', 'New image')}</h1>,
+        main: (
+          <div data-media-new="" className="grid justify-items-start gap-4">
+            <p className="text-muted-foreground">{t('media.newAbout', 'Choose an image and describe it. It is uploaded before it is saved.')}</p>
+            <Button type="button" onClick={() => setOpen(true)}>
+              <Upload className="size-4" aria-hidden />
+              {t('admin.upload.new', 'Upload new')}
+            </Button>
+            <NewImageDialog
+              open={open}
+              onOpenChange={(next) => {
+                setOpen(next)
+                if (!next) window.location.assign(list)
+              }}
+            />
+          </div>
+        ),
+      }}
+    />
+  )
+}