create-freakpunch 0.0.0-stage → 0.2.0

package/template/tools/new-module.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Creates a module with the standard structure and registers it:
+ *
+ *   npm run new-module -- orders --en "Orders" --tr "Siparişler" --group content
+ *
+ * The id is one lowercase word; it becomes the URL (/app/orders), the
+ * translation namespace and the permission prefix (orders.view, …).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+const root = path.resolve(import.meta.dirname, '..')
+const templates = path.join(import.meta.dirname, 'templates/module')
+
+function fail(message) {
+  console.error(`new-module: ${message}`)
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+const option = (name, fallback) => {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : fallback
+}
+const id = args[0]
+if (!id || id.startsWith('--')) fail('usage: npm run new-module -- <id> --en "Label" --tr "Etiket" [--group content]')
+if (!/^[a-z][a-z0-9]*$/.test(id)) fail(`"${id}" must be one lowercase word (letters and digits), e.g. orders`)
+
+const Name = id[0].toUpperCase() + id.slice(1)
+const values = { __id__: id, __Name__: Name, __labelEn__: option('en', Name), __labelTr__: option('tr', Name), __group__: option('group', 'content') }
+const fill = (text) => text.replace(/__(id|Name|labelEn|labelTr|group)__/g, (m) => values[m])
+
+const moduleDir = path.join(root, 'src/modules', id)
+if (existsSync(moduleDir)) fail(`src/modules/${id} already exists`)
+
+/** Inserts `line` above the `// marker` comment, keeping its indentation and the file's line endings. */
+function insert(file, entries) {
+  const abs = path.join(root, file)
+  let text = readFileSync(abs, 'utf8')
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  for (const [marker, line] of entries) {
+    const match = new RegExp(`^([ \\t]*)// ${marker}\\s*$`, 'm').exec(text)
+    if (!match) fail(`marker "// ${marker}" is missing from ${file}; add it where new entries belong`)
+    text = text.slice(0, match.index) + match[1] + line + eol + text.slice(match.index)
+  }
+  return () => writeFileSync(abs, text)
+}
+
+const config = readFileSync(path.join(root, 'src/app.config.ts'), 'utf8')
+if (!config.includes(`id: '${values.__group__}'`)) fail(`no nav group "${values.__group__}" in src/app.config.ts → navGroups`)
+
+// Check all three files first so a missing marker leaves nothing half-done.
+const writes = [
+  insert('src/modules/registry.ts', [
+    ['fp:module-imports', `import { ${id}Module } from './${id}'`],
+    ['fp:module-registry', `${id}: ${id}Module,`],
+  ]),
+  insert('src/modules/locales.ts', [
+    ['fp:locale-imports', `import ${id}En from './${id}/locales/en'`],
+    ['fp:locale-imports', `import ${id}Tr from './${id}/locales/tr'`],
+    ['fp:locale-en', `${id}: ${id}En,`],
+    ['fp:locale-tr', `${id}: ${id}Tr,`],
+  ]),
+  insert('src/app.config.ts', [['fp:modules', `${id}: true,`]]),
+]
+
+function copy(dir) {
+  for (const name of readdirSync(dir)) {
+    const source = path.join(dir, name)
+    if (statSync(source).isDirectory()) {
+      copy(source)
+      continue
+    }
+    const relative = fill(path.relative(templates, source)).replace(/\.tpl$/, '')
+    const target = path.join(moduleDir, relative)
+    mkdirSync(path.dirname(target), { recursive: true })
+    writeFileSync(target, fill(readFileSync(source, 'utf8')))
+  }
+}
+
+copy(templates)
+for (const write of writes) write()
+
+console.log(`Created src/modules/${id} and registered it (sidebar, routes, permissions, translations).
+
+Next:
+  1. Replace the sample fields in types.ts, the pages and both locale files.
+  2. Open /app/${id} in npm run dev.
+  3. Run npm run check.`)

package/template/tools/templates/module/api/__id__.mock.ts.tpl

@@ -0,0 +1,17 @@
+import { __id__Statuses, type __Name__Record } from '../types'
+
+/** 24 deterministic sample records. */
+export function create__Name__Seed(): __Name__Record[] {
+  const now = Date.now()
+  return Array.from({ length: 24 }, (_, i) => {
+    const at = new Date(now - i * 86_400_000).toISOString()
+    return {
+      id: `__id___${String(i + 1).padStart(4, '0')}`,
+      name: `__Name__ ${i + 1}`,
+      status: __id__Statuses[i % __id__Statuses.length],
+      notes: '',
+      createdAt: at,
+      updatedAt: at,
+    }
+  })
+}

package/template/tools/templates/module/api/__id__.service.ts.tpl

@@ -0,0 +1,51 @@
+import { createMockCollection, delay, notFound, paginate } from '@/core/api/mock'
+import { createRestService, type CrudService } from '@/core/api/rest'
+import { authMode } from '@/core/config/runtime'
+import { __id__FormSchema, type __Name__Filters, type __Name__Input, type __Name__Record } from '../types'
+import { create__Name__Seed } from './__id__.mock'
+
+/** The only contract screens depend on. Add module-specific methods here. */
+export type __Name__Service = CrudService<__Name__Record, __Name__Input, __Name__Filters>
+
+function createMock__Name__Service(): __Name__Service {
+  const db = createMockCollection('__id__', create__Name__Seed)
+  const find = (id: string) => db.find(id) ?? notFound('__Name__', id)
+
+  return {
+    async list(params) {
+      await delay()
+      const { status } = params.filters ?? {}
+      return paginate(db.all().filter((r) => !status || r.status === status), params, ['name'])
+    },
+
+    async get(id) {
+      await delay(150, 350)
+      return find(id)
+    },
+
+    async create(input) {
+      await delay()
+      const now = new Date().toISOString()
+      const record: __Name__Record = { ...__id__FormSchema.parse(input), id: crypto.randomUUID(), createdAt: now, updatedAt: now }
+      db.save([record, ...db.all()])
+      return record
+    },
+
+    async update(id, input) {
+      await delay()
+      const updated: __Name__Record = { ...find(id), ...__id__FormSchema.parse(input), updatedAt: new Date().toISOString() }
+      db.save(db.all().map((r) => (r.id === id ? updated : r)))
+      return updated
+    },
+
+    async remove(id) {
+      await delay()
+      find(id)
+      db.save(db.all().filter((r) => r.id !== id))
+    },
+  }
+}
+
+/** Demo data until auth points at a real backend; then the REST contract in BACKEND.md applies. */
+export const __id__Service: __Name__Service =
+  authMode === 'mock' ? createMock__Name__Service() : createRestService('/__id__')

package/template/tools/templates/module/hooks.ts.tpl

@@ -0,0 +1,57 @@
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+import type { ListParams } from '@/core/api/types'
+import { __id__Service } from './api/__id__.service'
+import type { __Name__Filters, __Name__Input } from './types'
+
+/** Query keys: invalidate `__id__Keys.all` after any write. */
+export const __id__Keys = {
+  all: ['__id__'] as const,
+  list: (params: ListParams<__Name__Filters>) => [...__id__Keys.all, 'list', params] as const,
+  detail: (id: string) => [...__id__Keys.all, 'detail', id] as const,
+}
+
+export function use__Name__List(params: ListParams<__Name__Filters>) {
+  return useQuery({
+    queryKey: __id__Keys.list(params),
+    queryFn: () => __id__Service.list(params),
+    placeholderData: keepPreviousData,
+  })
+}
+
+export function use__Name__Record(id: string | undefined) {
+  return useQuery({
+    queryKey: __id__Keys.detail(id ?? ''),
+    queryFn: () => __id__Service.get(id!),
+    enabled: Boolean(id),
+  })
+}
+
+/** Every row matching the current search and filters, for CSV export. */
+export function useExport__Name__(params: ListParams<__Name__Filters>) {
+  return async () => (await __id__Service.list({ ...params, page: 1, pageSize: 10_000 })).items
+}
+
+export function useCreate__Name__() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (input: __Name__Input) => __id__Service.create(input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: __id__Keys.all }),
+  })
+}
+
+export function useUpdate__Name__(id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (input: __Name__Input) => __id__Service.update(id, input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: __id__Keys.all }),
+  })
+}
+
+export function useDelete__Name__() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => __id__Service.remove(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: __id__Keys.all }),
+  })
+}

package/template/tools/templates/module/index.ts.tpl

@@ -0,0 +1,44 @@
+import { Blocks, Plus } from 'lucide-react'
+
+import { lazyPage } from '@/core/modules/lazy-page'
+import type { AppModule } from '@/core/modules/types'
+
+export const __id__Module: AppModule = {
+  id: '__id__',
+  nav: [
+    {
+      label: '__id__:nav',
+      path: '/app/__id__',
+      icon: Blocks,
+      group: '__group__',
+      permission: '__id__.view',
+    },
+  ],
+  quickActions: [
+    {
+      label: '__id__:quickActions.new',
+      description: '__id__:quickActions.newDescription',
+      path: '/app/__id__/new',
+      icon: Plus,
+      permission: '__id__.create',
+    },
+  ],
+  routes: [
+    {
+      path: '__id__',
+      handle: { crumb: '__id__:crumbs.list', permission: '__id__.view' },
+      children: [
+        { index: true, lazy: lazyPage(() => import('./pages/__id__-list-page')) },
+        { path: 'new', handle: { crumb: '__id__:crumbs.new', permission: '__id__.create' }, lazy: lazyPage(() => import('./pages/__id__-form-page')) },
+        {
+          path: ':id',
+          handle: { crumb: '__id__:crumbs.details' },
+          children: [
+            { index: true, lazy: lazyPage(() => import('./pages/__id__-detail-page')) },
+            { path: 'edit', handle: { crumb: '__id__:crumbs.edit', permission: '__id__.edit' }, lazy: lazyPage(() => import('./pages/__id__-form-page')) },
+          ],
+        },
+      ],
+    },
+  ],
+}

package/template/tools/templates/module/locales/en.ts.tpl

@@ -0,0 +1,51 @@
+/** __Name__ module strings (namespace `__id__`). */
+export default {
+  nav: '__labelEn__',
+  crumbs: { list: '__labelEn__', new: 'New', details: 'Details', edit: 'Edit' },
+  quickActions: { new: 'New record', newDescription: 'Add to __labelEn__' },
+  noun: 'records',
+  status: { active: 'Active', draft: 'Draft', archived: 'Archived' },
+  list: {
+    title: '__labelEn__',
+    description: 'Manage your records.',
+    new: 'New record',
+    export: 'Export CSV',
+    search: 'Search…',
+    filterStatus: 'Status',
+    allStatuses: 'All statuses',
+    columns: { name: 'Name', status: 'Status', updated: 'Updated' },
+    noMatchesTitle: 'No matching records',
+    noMatchesDescription: 'Try a different search or clear the filters.',
+    emptyTitle: 'No records yet',
+    emptyDescription: 'Create your first record to get started.',
+  },
+  delete: {
+    title: 'Delete “{{name}}”?',
+    description: 'This cannot be undone.',
+    deleting: 'Deleting…',
+    deleted: '{{name}} deleted',
+    bulkTitle_one: 'Delete {{count}} record?',
+    bulkTitle_other: 'Delete {{count}} records?',
+    bulkDeleted_one: '{{count}} record deleted',
+    bulkDeleted_other: '{{count}} records deleted',
+  },
+  detail: {
+    overview: 'Overview',
+    summary: 'Summary',
+    noNotes: 'No notes.',
+    fields: { status: 'Status', created: 'Created', updated: 'Updated' },
+  },
+  form: {
+    newTitle: 'New record',
+    editTitle: 'Edit {{name}}',
+    newDescription: 'Add a record.',
+    editDescription: 'Update this record.',
+    create: 'Create record',
+    created: 'Record created',
+    saved: 'Changes saved',
+    saveFailed: 'Could not save the record',
+    back: 'Back to the list',
+    sections: { details: 'Details', detailsDescription: 'The main information about this record.' },
+    fields: { name: 'Name', status: 'Status', notes: 'Notes', notesHint: 'Up to 500 characters.' },
+  },
+}

package/template/tools/templates/module/locales/tr.ts.tpl

@@ -0,0 +1,55 @@
+import type { Messages } from '@/core/i18n/types'
+import type en from './en'
+
+const tr: Messages<typeof en> = {
+  nav: '__labelTr__',
+  crumbs: { list: '__labelTr__', new: 'Yeni', details: 'Ayrıntılar', edit: 'Düzenle' },
+  quickActions: { new: 'Yeni kayıt', newDescription: 'Kayıt ekleyin' },
+  noun: 'kayıt',
+  status: { active: 'Aktif', draft: 'Taslak', archived: 'Arşivlendi' },
+  list: {
+    title: '__labelTr__',
+    description: 'Kayıtlarınızı yönetin.',
+    new: 'Yeni kayıt',
+    export: 'CSV olarak dışa aktar',
+    search: 'Ara…',
+    filterStatus: 'Durum',
+    allStatuses: 'Tüm durumlar',
+    columns: { name: 'Ad', status: 'Durum', updated: 'Güncellenme' },
+    noMatchesTitle: 'Eşleşen kayıt yok',
+    noMatchesDescription: 'Farklı bir arama deneyin veya filtreleri temizleyin.',
+    emptyTitle: 'Henüz kayıt yok',
+    emptyDescription: 'Başlamak için ilk kaydınızı oluşturun.',
+  },
+  delete: {
+    title: '“{{name}}” silinsin mi?',
+    description: 'Bu işlem geri alınamaz.',
+    deleting: 'Siliniyor…',
+    deleted: '{{name}} silindi',
+    bulkTitle_one: '{{count}} kayıt silinsin mi?',
+    bulkTitle_other: '{{count}} kayıt silinsin mi?',
+    bulkDeleted_one: '{{count}} kayıt silindi',
+    bulkDeleted_other: '{{count}} kayıt silindi',
+  },
+  detail: {
+    overview: 'Genel bakış',
+    summary: 'Özet',
+    noNotes: 'Not yok.',
+    fields: { status: 'Durum', created: 'Oluşturulma', updated: 'Güncellenme' },
+  },
+  form: {
+    newTitle: 'Yeni kayıt',
+    editTitle: '{{name}} kaydını düzenle',
+    newDescription: 'Kayıt ekleyin.',
+    editDescription: 'Bu kaydı güncelleyin.',
+    create: 'Kayıt oluştur',
+    created: 'Kayıt oluşturuldu',
+    saved: 'Değişiklikler kaydedildi',
+    saveFailed: 'Kayıt kaydedilemedi',
+    back: 'Listeye dön',
+    sections: { details: 'Ayrıntılar', detailsDescription: 'Bu kaydın temel bilgileri.' },
+    fields: { name: 'Ad', status: 'Durum', notes: 'Notlar', notesHint: 'En fazla 500 karakter.' },
+  },
+}
+
+export default tr

package/template/tools/templates/module/pages/__id__-detail-page.tsx.tpl

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useNavigate, useParams } from 'react-router'
+import { Pencil, Trash2 } from 'lucide-react'
+import { toast } from 'sonner'
+
+import { Button } from '@/components/ui/button'
+import { Can } from '@/core/auth/can'
+import { ButtonLink } from '@/core/components/button-link'
+import { useConfirm } from '@/core/components/confirm-dialog'
+import { Page, Panel } from '@/core/components/page'
+import { ErrorState, LoadingState } from '@/core/components/states'
+import { StatusBadge, type StatusTone } from '@/core/components/status-badge'
+import { useFormat } from '@/core/i18n/use-format'
+import { useDelete__Name__, use__Name__Record } from '../hooks'
+import type { __Name__Status } from '../types'
+
+const tones: Record<__Name__Status, StatusTone> = { active: 'success', draft: 'neutral', archived: 'warning' }
+
+export default function __Name__DetailPage() {
+  const { id } = useParams()
+  const query = use__Name__Record(id)
+  const remove = useDelete__Name__()
+  const confirm = useConfirm()
+  const navigate = useNavigate()
+  const { t } = useTranslation(['__id__', 'common'])
+  const fmt = useFormat()
+
+  if (query.isPending) return <LoadingState />
+  if (query.error) {
+    return (
+      <ErrorState
+        error={query.error}
+        onRetry={() => query.refetch()}
+        notFoundAction={
+          <ButtonLink to="/app/__id__" variant="outline">
+            {t('form.back')}
+          </ButtonLink>
+        }
+      />
+    )
+  }
+  const record = query.data
+
+  async function onDelete() {
+    const ok = await confirm({
+      title: t('delete.title', { name: record.name }),
+      description: t('delete.description'),
+      confirmLabel: t('common:actions.delete'),
+      destructive: true,
+    })
+    if (!ok) return
+    await remove.mutateAsync(record.id)
+    toast.success(t('delete.deleted', { name: record.name }))
+    navigate('/app/__id__', { replace: true })
+  }
+
+  return (
+    <Page
+      title={record.name}
+      actions={
+        <>
+          <Can permission="__id__.delete">
+            <Button variant="destructive" onClick={onDelete} disabled={remove.isPending}>
+              <Trash2 data-icon="inline-start" />
+              {t('common:actions.delete')}
+            </Button>
+          </Can>
+          <Can permission="__id__.edit">
+            <ButtonLink to="edit">
+              <Pencil data-icon="inline-start" />
+              {t('common:actions.edit')}
+            </ButtonLink>
+          </Can>
+        </>
+      }
+    >
+      <div className="grid gap-4 lg:grid-cols-3">
+        <Panel label={t('detail.overview')} className="lg:col-span-2" bodyClassName="p-5">
+          <p className="text-sm leading-relaxed text-pretty">{record.notes || t('detail.noNotes')}</p>
+        </Panel>
+        <Panel label={t('detail.summary')}>
+          <dl className="divide-y text-sm">
+            <Row label={t('detail.fields.status')}>
+              <StatusBadge tone={tones[record.status]}>{t(`status.${record.status}`)}</StatusBadge>
+            </Row>
+            <Row label={t('detail.fields.created')}>{fmt.date(record.createdAt)}</Row>
+            <Row label={t('detail.fields.updated')}>{fmt.relative(record.updatedAt)}</Row>
+          </dl>
+        </Panel>
+      </div>
+    </Page>
+  )
+}
+
+function Row({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div className="flex items-center justify-between gap-4 px-4 py-2.5">
+      <dt className="text-muted-foreground">{label}</dt>
+      <dd className="text-right font-medium tabular-nums">{children}</dd>
+    </div>
+  )
+}

package/template/tools/templates/module/pages/__id__-form-page.tsx.tpl

@@ -0,0 +1,121 @@
+import { Controller, useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useTranslation } from 'react-i18next'
+import { useNavigate, useParams } from 'react-router'
+import { toast } from 'sonner'
+
+import { Field, FieldDescription, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Textarea } from '@/components/ui/textarea'
+import { ButtonLink } from '@/core/components/button-link'
+import { FormFieldError } from '@/core/components/form-error'
+import { FormLayout, FormSection } from '@/core/components/form-page'
+import { Page } from '@/core/components/page'
+import { ErrorState, LoadingState } from '@/core/components/states'
+import { useCreate__Name__, useUpdate__Name__, use__Name__Record } from '../hooks'
+import { __id__FormSchema, __id__Statuses, type __Name__Input, type __Name__Record } from '../types'
+
+const empty: __Name__Input = { name: '', status: 'draft', notes: '' }
+
+/** /app/__id__/new and /app/__id__/:id/edit */
+export default function __Name__FormPage() {
+  const { id } = useParams()
+  const query = use__Name__Record(id)
+  const { t } = useTranslation('__id__')
+
+  if (!id) return <__Name__Form />
+  if (query.isPending) return <LoadingState />
+  if (query.error) {
+    return (
+      <ErrorState
+        error={query.error}
+        onRetry={() => query.refetch()}
+        notFoundAction={
+          <ButtonLink to="/app/__id__" variant="outline">
+            {t('form.back')}
+          </ButtonLink>
+        }
+      />
+    )
+  }
+  return <__Name__Form key={query.data.id} record={query.data} />
+}
+
+function __Name__Form({ record }: { record?: __Name__Record }) {
+  const navigate = useNavigate()
+  const create = useCreate__Name__()
+  const update = useUpdate__Name__(record?.id ?? '')
+  const { t } = useTranslation(['__id__', 'common'])
+  const isEdit = Boolean(record)
+
+  const form = useForm<__Name__Input>({
+    resolver: zodResolver(__id__FormSchema),
+    defaultValues: record ? { name: record.name, status: record.status, notes: record.notes } : empty,
+  })
+  const { register, control, handleSubmit, formState } = form
+  const { errors } = formState
+
+  const onSubmit = handleSubmit(async (values) => {
+    try {
+      const saved = isEdit ? await update.mutateAsync(values) : await create.mutateAsync(values)
+      toast.success(isEdit ? t('form.saved') : t('form.created'), { description: saved.name })
+      navigate(`/app/__id__/${saved.id}`)
+    } catch (e) {
+      toast.error(t('form.saveFailed'), { description: e instanceof Error ? e.message : undefined })
+    }
+  })
+
+  const statusItems = __id__Statuses.map((s) => ({ value: s, label: t(`status.${s}`) }))
+
+  return (
+    <Page
+      title={isEdit ? t('form.editTitle', { name: record!.name }) : t('form.newTitle')}
+      description={isEdit ? t('form.editDescription') : t('form.newDescription')}
+    >
+      <FormLayout
+        onSubmit={onSubmit}
+        submitLabel={isEdit ? t('common:actions.saveChanges') : t('form.create')}
+        isSubmitting={formState.isSubmitting}
+        isDirty={!isEdit || formState.isDirty}
+        onCancel={() => navigate(-1)}
+      >
+        <FormSection title={t('form.sections.details')} description={t('form.sections.detailsDescription')}>
+          <Field data-invalid={!!errors.name}>
+            <FieldLabel htmlFor="name">{t('form.fields.name')}</FieldLabel>
+            <Input id="name" autoFocus={!isEdit} aria-invalid={!!errors.name} {...register('name')} />
+            <FormFieldError error={errors.name} />
+          </Field>
+          <Field data-invalid={!!errors.status}>
+            <FieldLabel htmlFor="status">{t('form.fields.status')}</FieldLabel>
+            <Controller
+              control={control}
+              name="status"
+              render={({ field }) => (
+                <Select items={statusItems} value={field.value} onValueChange={(v) => v && field.onChange(v)}>
+                  <SelectTrigger id="status" className="w-full" onBlur={field.onBlur}>
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {statusItems.map((s) => (
+                      <SelectItem key={s.value} value={s.value}>
+                        {s.label}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              )}
+            />
+            <FormFieldError error={errors.status} />
+          </Field>
+          <Field data-invalid={!!errors.notes}>
+            <FieldLabel htmlFor="notes">{t('form.fields.notes')}</FieldLabel>
+            <Textarea id="notes" rows={4} aria-invalid={!!errors.notes} {...register('notes')} />
+            <FieldDescription>{t('form.fields.notesHint')}</FieldDescription>
+            <FormFieldError error={errors.notes} />
+          </Field>
+        </FormSection>
+      </FormLayout>
+    </Page>
+  )
+}