create-freakpunch 0.1.0 → 0.2.0

package/template/src/pages/settings/company/modules-page.tsx

@@ -5,8 +5,10 @@ import { Switch } from '@/components/ui/switch'
 import { appConfig } from '@/app.config'
 import { moduleActions } from '@/core/auth/permissions'
 import { Page } from '@/core/components/page'
+import { EmptyState } from '@/core/components/states'
 import { StatusBadge } from '@/core/components/status-badge'
 import { useAnyT } from '@/core/i18n/keys'
+import type { AppModule } from '@/core/modules/types'
 import { moduleRegistry, type ModuleId } from '@/modules/registry'
 
 const moduleIds = Object.keys(moduleRegistry) as ModuleId[]
@@ -24,9 +26,15 @@ export default function ModulesPage() {
           <Trans t={t} i18nKey="modules.note" components={{ code: <code className="tabular-nums text-[11px] text-foreground" /> }} />
         </span>
       </p>
-      <ul className="divide-y rounded-xl border bg-card shadow-(--shadow-card)">
+      {moduleIds.length === 0 && (
+        <div className="rounded-xl border bg-card shadow-(--shadow-card)">
+          <EmptyState icon={<Blocks />} title={t('modules.emptyTitle')} description={t('modules.emptyDescription')} />
+        </div>
+      )}
+      <ul className="divide-y rounded-xl border bg-card shadow-(--shadow-card) empty:hidden">
         {moduleIds.map((id) => {
-          const module = moduleRegistry[id]
+          // Typed explicitly: with no modules registered yet the registry's type is empty.
+          const module: AppModule = moduleRegistry[id]
           const nav = module.nav[0]
           const Icon = nav?.icon ?? Blocks
           const name = nav ? anyT(nav.label) : id

package/template/src/pages/settings/company/roles-page.tsx

@@ -6,6 +6,7 @@ import { Table, TableBody, TableCell, TableHeader, TableRow } from '@/components
 import { TableHeaderCell } from '@/core/components/data-table/table-header-cell'
 import { hasPermission, matrixActions, permissionMatrix, roles, type Role } from '@/core/auth/permissions'
 import { Page, Panel } from '@/core/components/page'
+import type { AppModule } from '@/core/modules/types'
 import { Segmented } from '@/core/components/segmented'
 import { Skeleton } from '@/components/ui/skeleton'
 import { useAnyT } from '@/core/i18n/keys'
@@ -27,7 +28,7 @@ export default function RolesPage() {
 
   const rowLabel = (row: (typeof permissionMatrix)[number]) =>
     row.module
-      ? anyT(moduleRegistry[row.module].nav[0]?.label ?? 'common:nav.dashboard')
+      ? anyT((moduleRegistry[row.module] as AppModule).nav[0]?.label ?? 'common:nav.dashboard')
       : t(`roles.resources.${row.id as 'dashboard'}`)
 
   return (

package/template/src/pages/setup-page.tsx

@@ -0,0 +1,387 @@
+import { useEffect, useState } from 'react'
+import { Controller, useForm, useWatch } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useTranslation } from 'react-i18next'
+import { Check, ImageOff } from 'lucide-react'
+import { toast } from 'sonner'
+import { z } from 'zod'
+
+import { Button } from '@/components/ui/button'
+import { Card, CardContent } from '@/components/ui/card'
+import { Field, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Spinner } from '@/components/ui/spinner'
+import { appConfig } from '@/app.config'
+import { ApiError } from '@/core/api/http'
+import { checkPassword, defaultPasswordPolicy } from '@/core/company/password-policy'
+import { currencies, type Currency } from '@/core/company/types'
+import { FormFieldError } from '@/core/components/form-error'
+import { ImageUpload } from '@/core/components/image-upload'
+import { Segmented } from '@/core/components/segmented'
+import { authMode } from '@/core/config/runtime'
+import { setLanguage, currentLanguage } from '@/core/i18n/i18n'
+import { vmsg } from '@/core/i18n/keys'
+import { LanguageSwitcher } from '@/core/i18n/language-switcher'
+import { languageNames, languages, type Language } from '@/core/i18n/types'
+import { timeZones } from '@/core/preferences/preferences-store'
+import { setupService } from '@/core/setup/setup.service'
+import { brandPresets, type BrandPresetId } from '@/core/theme/brand'
+import { useBrand } from '@/core/theme/brand-context'
+import { ThemeToggle } from '@/core/theme/theme-toggle'
+import { cn } from '@/lib/utils'
+import { PasswordStrength } from '@/pages/settings/account/components/password-strength'
+
+const required = (max: number) =>
+  z
+    .string()
+    .trim()
+    .min(1, vmsg('validation.required'))
+    .max(max, vmsg('validation.maxChars', { max }))
+
+const schema = z
+  .object({
+    companyName: required(80),
+    language: z.enum(languages),
+    timeZone: z.string(),
+    currency: z.enum(currencies),
+    firstName: required(60),
+    lastName: required(60),
+    email: z.string().trim().min(1, vmsg('validation.required')).pipe(z.email(vmsg('validation.email'))),
+    password: z.string(),
+    confirmPassword: z.string(),
+    brand: z.string(),
+    logo: z.string().optional(),
+  })
+  .superRefine((v, ctx) => {
+    if (!checkPassword(defaultPasswordPolicy, v.password).valid) {
+      ctx.addIssue({ code: 'custom', path: ['password'], message: vmsg('setup:admin.passwordWeak') })
+    }
+    if (v.password !== v.confirmPassword) {
+      ctx.addIssue({ code: 'custom', path: ['confirmPassword'], message: vmsg('setup:admin.passwordMismatch') })
+    }
+  })
+type Values = z.infer<typeof schema>
+
+const steps = ['company', 'admin', 'branding', 'review'] as const
+const stepFields: Record<(typeof steps)[number], (keyof Values)[]> = {
+  company: ['companyName', 'language', 'timeZone', 'currency'],
+  admin: ['firstName', 'lastName', 'email', 'password', 'confirmPassword'],
+  branding: ['brand', 'logo'],
+  review: [],
+}
+const presetIds = Object.keys(brandPresets) as BrandPresetId[]
+
+function detectedTimeZone() {
+  const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
+  return (timeZones as readonly string[]).includes(zone) ? zone : timeZones[0]!
+}
+
+/** First-run wizard: company, Owner account, look, review. See core/setup. */
+export default function SetupPage() {
+  const { t, i18n } = useTranslation(['setup', 'common', 'company'])
+  const [step, setStep] = useState(0)
+  const [done, setDone] = useState(false)
+  const { setBrand, previewBrand, defaultBrand } = useBrand()
+
+  const form = useForm<Values>({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      companyName: '',
+      language: currentLanguage(),
+      timeZone: detectedTimeZone(),
+      currency: currentLanguage() === 'tr' ? 'TRY' : (appConfig.currency as Currency),
+      firstName: '',
+      lastName: '',
+      email: '',
+      password: '',
+      confirmPassword: '',
+      brand: typeof defaultBrand === 'string' ? defaultBrand : 'indigo',
+    },
+  })
+  const { register, control, handleSubmit, trigger, getValues, setValue, formState } = form
+  const { errors, isSubmitting } = formState
+  const password = useWatch({ control, name: 'password' })
+  const brand = useWatch({ control, name: 'brand' }) as BrandPresetId
+  const companyName = useWatch({ control, name: 'companyName' })
+  const current = steps[step]!
+
+  useEffect(() => {
+    document.title = t('title')
+  }, [t])
+  useEffect(() => previewBrand(brand), [brand, previewBrand])
+  // The language switcher in the corner and the field on the first step are one setting.
+  useEffect(() => setValue('language', currentLanguage()), [i18n.language, setValue])
+
+  const submit = handleSubmit(async (v) => {
+    try {
+      await setupService.complete({
+        company: { name: v.companyName, language: v.language, timeZone: v.timeZone, currency: v.currency },
+        admin: { firstName: v.firstName, lastName: v.lastName, email: v.email, password: v.password },
+        branding: { brand: v.brand as BrandPresetId, logo: v.logo },
+      })
+      setBrand(v.brand as BrandPresetId)
+      setDone(true)
+    } catch (e) {
+      const insecure = e instanceof ApiError && e.message === 'insecure_context'
+      toast.error(t('failed'), { description: insecure ? t('insecure') : e instanceof Error ? e.message : undefined })
+    }
+  })
+
+  async function next() {
+    if (await trigger(stepFields[current], { shouldFocus: true })) setStep((s) => s + 1)
+  }
+
+  const zoneItems = timeZones.map((z) => ({ value: z, label: z }))
+  const currencyItems = currencies.map((c) => ({ value: c, label: c }))
+  const values = getValues()
+
+  return (
+    <div className="relative grid min-h-svh grid-rows-[1fr_auto_1fr] justify-items-center bg-canvas px-4 py-14">
+      <div className="absolute top-3 right-3 flex items-center gap-1.5 sm:top-4 sm:right-4">
+        <LanguageSwitcher />
+        <ThemeToggle />
+      </div>
+
+      <Card className="row-start-2 w-full max-w-lg gap-0 rounded-(--radius-panel) py-0 shadow-(--shadow-panel)">
+        <CardContent className="p-6 sm:p-8">
+          {done ? (
+            <div className="flex flex-col items-center gap-4 py-6 text-center">
+              <span className="flex size-12 items-center justify-center rounded-xl bg-primary text-primary-foreground">
+                <Check className="size-6" />
+              </span>
+              <div className="flex flex-col gap-1">
+                <h1 className="text-2xl font-semibold tracking-tight">{t('done.title')}</h1>
+                <p className="text-sm text-balance text-muted-foreground">{t('done.description', { name: values.companyName })}</p>
+              </div>
+              {/* A full load so every service starts from the data just saved. */}
+              <Button size="lg" onClick={() => window.location.assign(`${import.meta.env.BASE_URL}app`)}>
+                {t('done.open')}
+              </Button>
+            </div>
+          ) : (
+            <form
+              noValidate
+              onSubmit={(e) => {
+                e.preventDefault()
+                if (current === 'review') void submit(e)
+                else void next()
+              }}
+              className="flex flex-col gap-6"
+            >
+              <header className="flex flex-col gap-3">
+                <div className="flex gap-1" aria-hidden>
+                  {steps.map((s, i) => (
+                    <span key={s} className={cn('h-1 flex-1 rounded-full', i <= step ? 'bg-primary' : 'bg-fill-3')} />
+                  ))}
+                </div>
+                <p className="label-caps">{t('progress', { step: step + 1, total: steps.length })}</p>
+                <div className="flex flex-col gap-1">
+                  <h1 className="text-2xl font-semibold tracking-tight">{t(`${current}.title`)}</h1>
+                  <p className="text-sm text-muted-foreground">{t(`${current}.description`)}</p>
+                </div>
+              </header>
+
+              {current === 'company' && (
+                <div className="flex flex-col gap-4">
+                  <Field data-invalid={!!errors.companyName}>
+                    <FieldLabel htmlFor="companyName">{t('company.name')}</FieldLabel>
+                    <Input id="companyName" autoFocus autoComplete="organization" aria-invalid={!!errors.companyName} {...register('companyName')} />
+                    <FormFieldError error={errors.companyName} />
+                  </Field>
+                  <Field>
+                    <FieldLabel>{t('company.language')}</FieldLabel>
+                    <Controller
+                      control={control}
+                      name="language"
+                      render={({ field }) => (
+                        <div className="w-fit">
+                          <Segmented
+                            label={t('company.language')}
+                            value={field.value}
+                            onChange={(lng: Language) => {
+                              field.onChange(lng)
+                              setLanguage(lng)
+                            }}
+                            options={languages.map((l) => ({ value: l, label: languageNames[l] }))}
+                          />
+                        </div>
+                      )}
+                    />
+                  </Field>
+                  <div className="grid gap-4 sm:grid-cols-2">
+                    <Field>
+                      <FieldLabel htmlFor="timeZone">{t('company.timeZone')}</FieldLabel>
+                      <Controller
+                        control={control}
+                        name="timeZone"
+                        render={({ field }) => (
+                          <Select items={zoneItems} value={field.value} onValueChange={(v) => v && field.onChange(v)}>
+                            <SelectTrigger id="timeZone" className="w-full">
+                              <SelectValue />
+                            </SelectTrigger>
+                            <SelectContent>
+                              {zoneItems.map((z) => (
+                                <SelectItem key={z.value} value={z.value}>
+                                  {z.label}
+                                </SelectItem>
+                              ))}
+                            </SelectContent>
+                          </Select>
+                        )}
+                      />
+                    </Field>
+                    <Field>
+                      <FieldLabel htmlFor="currency">{t('company.currency')}</FieldLabel>
+                      <Controller
+                        control={control}
+                        name="currency"
+                        render={({ field }) => (
+                          <Select items={currencyItems} value={field.value} onValueChange={(v) => v && field.onChange(v)}>
+                            <SelectTrigger id="currency" className="w-full">
+                              <SelectValue />
+                            </SelectTrigger>
+                            <SelectContent>
+                              {currencyItems.map((c) => (
+                                <SelectItem key={c.value} value={c.value}>
+                                  {c.label}
+                                </SelectItem>
+                              ))}
+                            </SelectContent>
+                          </Select>
+                        )}
+                      />
+                    </Field>
+                  </div>
+                </div>
+              )}
+
+              {current === 'admin' && (
+                <div className="flex flex-col gap-4">
+                  <div className="grid gap-4 sm:grid-cols-2">
+                    <Field data-invalid={!!errors.firstName}>
+                      <FieldLabel htmlFor="firstName">{t('admin.firstName')}</FieldLabel>
+                      <Input id="firstName" autoFocus autoComplete="given-name" aria-invalid={!!errors.firstName} {...register('firstName')} />
+                      <FormFieldError error={errors.firstName} />
+                    </Field>
+                    <Field data-invalid={!!errors.lastName}>
+                      <FieldLabel htmlFor="lastName">{t('admin.lastName')}</FieldLabel>
+                      <Input id="lastName" autoComplete="family-name" aria-invalid={!!errors.lastName} {...register('lastName')} />
+                      <FormFieldError error={errors.lastName} />
+                    </Field>
+                  </div>
+                  <Field data-invalid={!!errors.email}>
+                    <FieldLabel htmlFor="email">{t('admin.email')}</FieldLabel>
+                    <Input id="email" type="email" autoComplete="email" aria-invalid={!!errors.email} {...register('email')} />
+                    <FormFieldError error={errors.email} />
+                  </Field>
+                  <Field data-invalid={!!errors.password}>
+                    <FieldLabel htmlFor="password">{t('admin.password')}</FieldLabel>
+                    <Input id="password" type="password" autoComplete="new-password" aria-invalid={!!errors.password} {...register('password')} />
+                    <FormFieldError error={errors.password} />
+                  </Field>
+                  <PasswordStrength password={password} policy={defaultPasswordPolicy} />
+                  <Field data-invalid={!!errors.confirmPassword}>
+                    <FieldLabel htmlFor="confirmPassword">{t('admin.confirmPassword')}</FieldLabel>
+                    <Input id="confirmPassword" type="password" autoComplete="new-password" aria-invalid={!!errors.confirmPassword} {...register('confirmPassword')} />
+                    <FormFieldError error={errors.confirmPassword} />
+                  </Field>
+                </div>
+              )}
+
+              {current === 'branding' && (
+                <div className="flex flex-col gap-5">
+                  <Field>
+                    <FieldLabel>{t('branding.color')}</FieldLabel>
+                    <Controller
+                      control={control}
+                      name="brand"
+                      render={({ field }) => (
+                        <div className="flex flex-wrap gap-2">
+                          {presetIds.map((id) => (
+                            <button
+                              key={id}
+                              type="button"
+                              aria-pressed={field.value === id}
+                              aria-label={t(`company:branding.presets.${id}`)}
+                              title={t(`company:branding.presets.${id}`)}
+                              onClick={() => field.onChange(id)}
+                              style={{ background: brandPresets[id].color }}
+                              className={cn(
+                                'flex size-9 items-center justify-center rounded-lg outline-none ring-offset-2 ring-offset-card focus-visible:ring-2 focus-visible:ring-ring',
+                                field.value === id && 'ring-2 ring-foreground',
+                              )}
+                            >
+                              {field.value === id && <Check className="size-4" style={{ color: brandPresets[id].foreground }} />}
+                            </button>
+                          ))}
+                        </div>
+                      )}
+                    />
+                  </Field>
+                  <Field>
+                    <FieldLabel>{t('branding.logo')}</FieldLabel>
+                    <Controller
+                      control={control}
+                      name="logo"
+                      render={({ field }) => (
+                        <ImageUpload
+                          value={field.value}
+                          onChange={field.onChange}
+                          onError={(err) => toast.error(t(`company:branding.imageError.${err}`))}
+                          label={t('branding.logo')}
+                          preview={(src) => (
+                            <div className="flex size-12 shrink-0 items-center justify-center overflow-hidden rounded-xl border bg-fill-1 text-muted-foreground">
+                              {src ? <img src={src} alt="" className="max-h-full max-w-full object-contain" /> : <ImageOff className="size-4" />}
+                            </div>
+                          )}
+                        />
+                      )}
+                    />
+                  </Field>
+                </div>
+              )}
+
+              {current === 'review' && (
+                <dl className="divide-y rounded-xl border text-sm">
+                  {[
+                    [t('company.name'), companyName],
+                    [t('company.language'), languageNames[values.language]],
+                    [t('company.timeZone'), values.timeZone],
+                    [t('company.currency'), values.currency],
+                    [t('review.admin'), `${values.firstName} ${values.lastName}`],
+                    [t('admin.email'), values.email],
+                    [t('branding.color'), t(`company:branding.presets.${brand}`)],
+                  ].map(([label, value]) => (
+                    <div key={label} className="flex items-center justify-between gap-4 px-4 py-2.5">
+                      <dt className="text-muted-foreground">{label}</dt>
+                      <dd className="min-w-0 truncate text-right font-medium">{value}</dd>
+                    </div>
+                  ))}
+                </dl>
+              )}
+
+              <footer className="flex items-center justify-between gap-2">
+                {step > 0 ? (
+                  <Button type="button" variant="ghost" disabled={isSubmitting} onClick={() => setStep((s) => s - 1)}>
+                    {t('common:actions.back')}
+                  </Button>
+                ) : (
+                  <span />
+                )}
+                <Button type="submit" disabled={isSubmitting}>
+                  {isSubmitting && <Spinner data-icon="inline-start" />}
+                  {current === 'review' ? t('finish') : t('next')}
+                </Button>
+              </footer>
+            </form>
+          )}
+        </CardContent>
+      </Card>
+
+      {authMode === 'mock' && (
+        <p className="row-start-3 max-w-md self-end pt-4 text-center text-xs text-balance text-muted-foreground">{t('localNote')}</p>
+      )}
+    </div>
+  )
+}

package/template/src/router.tsx

@@ -1,26 +1,31 @@
-import { createBrowserRouter, Navigate, Outlet } from 'react-router'
+import { createBrowserRouter, Navigate } from 'react-router'
 
 import { showLanding } from '@/core/config/runtime'
 import { AppShell } from '@/core/layout/app-shell'
 import { lazyPage } from '@/core/modules/lazy-page'
 import type { RouteHandle } from '@/core/modules/types'
+import { SetupGate } from '@/core/setup/setup-gate'
 import { enabledModules } from '@/modules/registry'
 import NotFoundPage, { RouteError } from '@/pages/not-found-page'
 import { settingsRoutes } from '@/pages/settings/settings-routes'
 
 const home: RouteHandle = { crumb: 'common:nav.dashboard' }
 
+// A glob, not an import: the marketing page only exists in the public demo.
+const landing = Object.values(import.meta.glob<{ default: React.ComponentType }>('/src/pages/landing-page.tsx'))[0]
+
 export const router = createBrowserRouter([
   {
     // Full-screen pages share one error screen.
-    element: <Outlet />,
+    element: <SetupGate />,
     errorElement: <RouteError />,
     // Shown while the first lazy route loads.
     hydrateFallbackElement: <div className="min-h-svh bg-canvas" />,
     children: [
-      showLanding
-        ? { path: '/', lazy: lazyPage(() => import('@/pages/landing-page')) }
+      showLanding && landing
+        ? { path: '/', lazy: lazyPage(landing) }
         : { path: '/', element: <Navigate to="/app" replace /> },
+      { path: '/setup', lazy: lazyPage(() => import('@/pages/setup-page')) },
       { path: '/login', lazy: lazyPage(() => import('@/pages/login-page')) },
       {
         path: '/app',

package/template/tools/new-module.mjs

@@ -1,90 +1,90 @@
-#!/usr/bin/env node
-/**
- * Creates a module with the standard structure and registers it:
- *
- *   npm run new-module -- assets --en "Assets" --tr "Zimmet" --group content
- *
- * The id is one lowercase word; it becomes the URL (/app/assets), the
- * translation namespace and the permission prefix (assets.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. assets`)
-
-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.`)
+#!/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.`)