@adula/create-app 0.2.0-alpha.1

package/LICENSE

@@ -0,0 +1,10 @@
+# The MIT License
+
+Copyright (c) 2023
+Copyright (c) 2026 adula contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @adula/create-app
+
+Creates a complete, project-owned AdonisJS 7 application with adula, React/Inertia,
+shadcn/ui, authentication, administration and the managed business-design skill.
+Version 0.2.0-alpha.1 is **unreleased**; registry commands become available after publication.
+
+```sh
+npm create @adula/app@alpha my-app
+```
+
+Requires Node.js 24+ and npm. The default provisions PostgreSQL 17 and Redis 7
+through an existing Docker installation with Compose. pnpm is bootstrapped through
+npm and installed as a project-local development dependency; neither a global
+pnpm installation nor a pre-existing AdonisJS application is required.
+
+The wizard requests the company name, administrator email and company identity.
+An optional identity JSON file contains `primaryColor` (six-digit hex), `logo`
+(local PNG/JPEG/WebP path relative to the JSON), `fontFamily` and `guidelines`.
+Known identity is applied immediately. Missing identity remains explicitly pending
+in `docs/design-identity.md`; no official branding is invented.
+
+Terminal prompts and errors use English so they remain readable in terminals
+without Arabic shaping. The application stays Arabic. Installation shows six real
+stages, with color and a spinner in interactive terminals. `NO_COLOR=1`, redirected
+output and dumb terminals use plain progress lines. Detailed child-command output
+is retained privately in ignored `tmp/install.log`; failures identify that log.
+
+```sh
+npm create @adula/app@alpha my-app -- --company "My company" --admin-email admin@example.com --identity ./brand.json --yes
+```
+
+For existing services, add `--services existing --connection ./local.json`:
+
+```json
+{
+  "postgres": {
+    "host": "127.0.0.1",
+    "port": 5432,
+    "user": "adula",
+    "password": "YOUR_LOCAL_PASSWORD"
+  },
+  "redis": { "host": "127.0.0.1", "port": 6379 }
+}
+```
+
+Keep this file private. The PostgreSQL role needs `CREATEDB`; the command creates
+fresh development/test databases. It refuses an existing destination directory
+with content or a pre-existing database. Database failures preserve files/data
+for inspection. Local administrator credentials are saved in ignored
+`tmp/dev-admin.txt`, never printed. No educational business modules are installed.
+An optional `--database name` selects a fresh database name (lowercase letters,
+digits and underscores, at most 50 characters); an existing name is still refused.
+Values containing dotenv interpolation or quote characters are stored in private
+`tmp/env` files and loaded through AdonisJS's `file:` identifier without alteration.
+
+After creation: `cd my-app` and `npm run dev`. Workers and scheduler are separate
+runtime processes documented in the application README. SMTP, OAuth, S3, production
+hosting and off-site backups need real configuration; no external accounts are
+created. Node.js and Docker themselves are host prerequisites.
+
+Before publication, run the packed CLI with npm exec and `--packages` pointing
+to the directory containing matching `adula-kit-VERSION.tgz` and
+`adula-ui-VERSION.tgz`. `pnpm test:create` exercises this path from an empty folder.

package/build/cli.mjs

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+import { Progress } from './progress.mjs'
+import { parseArgs } from 'node:util'
+import { createInterface } from 'node:readline/promises'
+import { randomBytes } from 'node:crypto'
+import { readFile, realpath } from 'node:fs/promises'
+import { resolve, join, delimiter } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import {
+  assertEmpty,
+  projectName,
+  renderProject,
+  writeNew,
+  dotenv,
+  prepareEnvironment,
+  composeFile,
+  readIdentity,
+  readJson,
+} from './project.mjs'
+import {
+  run,
+  packageManager,
+  packageManagerBin,
+  freePort,
+  pingRedis,
+  createDatabases,
+  databaseNames,
+  childEnvironment,
+} from './system.mjs'
+
+export const help = `Create a new business application with AdonisJS and adula
+
+  npm create @adula/app@alpha my-app
+
+  --company "Company name"     Company display name (Arabic supported)
+  --admin-email email          Administrator email
+  --identity brand.json        Company logo, primaryColor, fontFamily and guidelines
+  --services docker|existing   Default: Docker; requires Docker Compose
+  --connection local.json      PostgreSQL and Redis profile for existing services
+  --database name              Fresh database name; existing databases are rejected
+  --packages directory         Local kit and UI archives for pre-publication testing
+  --yes                       Noninteractive; requires company and administrator email
+  --help                      Show help
+
+Requires Node.js 24+ and npm. Installs pnpm, AdonisJS, adula, the Arabic UI,
+databases, administrator and agent skills. External SMTP, OAuth and S3 require
+your configuration. Credentials are saved privately in tmp/dev-admin.txt.
+Set NO_COLOR=1 for plain progress output.
+`
+
+function validateConnection(profile) {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile))
+    throw new Error('The connection file must contain a JSON object.')
+  for (const key of ['postgres', 'redis']) {
+    const value = profile[key]
+    if (
+      !value ||
+      typeof value.host !== 'string' ||
+      !value.host ||
+      /[\r\n\0]/.test(value.host) ||
+      !Number.isInteger(value.port) ||
+      value.port < 1 ||
+      value.port > 65535
+    )
+      throw new Error(`Invalid ${key} connection: provide host and port.`)
+    if (value.password !== undefined && typeof value.password !== 'string')
+      throw new Error(`Invalid ${key} password.`)
+  }
+  if (
+    typeof profile.postgres.user !== 'string' ||
+    !profile.postgres.user ||
+    typeof profile.postgres.password !== 'string'
+  )
+    throw new Error('Provide PostgreSQL user and password. The account needs CREATEDB permission.')
+  if (profile.postgres.database || profile.postgres.testDatabase)
+    throw new Error(
+      'Do not specify an existing database. Setup creates two fresh databases; maintenanceDatabase is only for the administrative connection.'
+    )
+  return profile
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { values, positionals } = parseArgs({
+    args: argv.filter((arg) => arg !== '--'),
+    allowPositionals: true,
+    options: {
+      'help': { type: 'boolean' },
+      'yes': { type: 'boolean' },
+      'company': { type: 'string' },
+      'admin-email': { type: 'string' },
+      'identity': { type: 'string' },
+      'services': { type: 'string', default: 'docker' },
+      'connection': { type: 'string' },
+      'database': { type: 'string' },
+      'packages': { type: 'string' },
+    },
+  })
+  if (values.help) {
+    console.log(help)
+    return
+  }
+  if (Number(process.versions.node.split('.')[0]) < 24)
+    throw new Error('Creating an application requires Node.js 24 or later.')
+  if (positionals.length > 1) throw new Error('Specify one project directory.')
+  if (values.database !== undefined && !/^[a-z][a-z0-9_]{0,49}$/.test(values.database))
+    throw new Error(
+      'Database name must start with a lowercase letter and use lowercase letters, digits or underscores (up to 50 characters).'
+    )
+  if (!['docker', 'existing'].includes(values.services))
+    throw new Error('--services must be docker or existing.')
+  if (values.services === 'existing' && !values.connection)
+    throw new Error('Provide --connection when using existing services.')
+  if (values.services === 'docker' && values.connection)
+    throw new Error('--connection is only available for existing services.')
+  let directory = positionals[0]
+  let company = values.company
+  let email = values['admin-email']
+  let identityFile = values.identity
+  const interactive = process.stdin.isTTY && !values.yes
+  if (interactive) {
+    const prompt = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    })
+    try {
+      directory ||= await prompt.question('Application directory: ')
+      company ||= await prompt.question('Company name as it should appear in the application: ')
+      email ||= await prompt.question('Administrator email: ')
+      identityFile ||= await prompt.question(
+        'Company identity JSON (logo, colors, fonts, guidelines; Enter to record as pending): '
+      )
+    } finally {
+      prompt.close()
+    }
+  }
+  if (!directory || !company || !email)
+    throw new Error('Provide a directory, --company and --admin-email, or run interactively.')
+  if (!/^[^\s@'\0]+@[^\s@'\0]+\.[^\s@'\0]+$/.test(email) || email.length > 254)
+    throw new Error('Invalid administrator email.')
+  const target = resolve(directory)
+  const name = projectName(target)
+  await assertEmpty(target)
+  const identity = await readIdentity(identityFile || undefined, company)
+  const template = JSON.parse(await readFile(new URL('./template.json', import.meta.url), 'utf8'))
+  const manager = await packageManager()
+  const suffix = randomBytes(6).toString('hex')
+  const names = values.database
+    ? { database: values.database, testDatabase: `${values.database}_test` }
+    : databaseNames(name, suffix)
+  const ports = new Set()
+  const allocatePort = async () => {
+    let port = await freePort()
+    while (ports.has(port)) port = await freePort()
+    ports.add(port)
+    return port
+  }
+  const env = childEnvironment()
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH'
+  env[pathKey] = [
+    await packageManagerBin(),
+    join(target, 'node_modules/.bin'),
+    env[pathKey] ?? '',
+  ].join(delimiter)
+  let profile
+  const progress = new Progress()
+  try {
+    progress.start('Check services and prepare configuration')
+    if (values.services === 'docker') {
+      await run('docker', ['compose', 'version'], { env, quiet: true })
+      await run('docker', ['info'], { env, quiet: true })
+      profile = {
+        postgres: {
+          host: '127.0.0.1',
+          port: await allocatePort(),
+          user: 'adula',
+          password: randomBytes(24).toString('hex'),
+        },
+        redis: { host: '127.0.0.1', port: await allocatePort() },
+      }
+    } else {
+      profile = validateConnection(await readJson(resolve(values.connection), 'connection'))
+      await pingRedis(profile.redis)
+    }
+    const port = await allocatePort()
+    const testPort = await allocatePort()
+    const appEnv = {
+      TZ: 'UTC',
+      NODE_ENV: 'development',
+      HOST: '127.0.0.1',
+      PORT: port,
+      LOG_LEVEL: 'info',
+      APP_KEY: randomBytes(32).toString('base64url'),
+      APP_URL: `http://127.0.0.1:${port}`,
+      ADULA_NAMESPACE: `${name}-${suffix}`,
+      COMPOSE_PROJECT_NAME: `${name}-${suffix}`,
+      SESSION_DRIVER: 'database',
+      DB_HOST: profile.postgres.host,
+      DB_PORT: profile.postgres.port,
+      DB_USER: profile.postgres.user,
+      DB_PASSWORD: profile.postgres.password,
+      DB_DATABASE: names.database,
+      REDIS_HOST: profile.redis.host,
+      REDIS_PORT: profile.redis.port,
+      ...(profile.redis.password ? { REDIS_PASSWORD: profile.redis.password } : {}),
+      DRIVE_DISK: 'local',
+      LIMITER_STORE: 'redis',
+      MAIL_MAILER: 'smtp',
+      MAIL_FROM_NAME: identity.company,
+      MAIL_FROM_ADDRESS: email,
+      SMTP_HOST: '127.0.0.1',
+      SMTP_PORT: 1025,
+    }
+    // Validate all local archives before the first write.
+    if (values.packages)
+      for (const kind of ['kit', 'ui'])
+        await readFile(resolve(values.packages, `adula-${kind}-${template.version}.tgz`))
+    progress.start('Create AdonisJS application and company identity')
+    await renderProject(target, template, {
+      name,
+      identity,
+      packageFiles: values.packages,
+    })
+    const encodedEnv = await prepareEnvironment(target, appEnv)
+    await writeNew(target, '.env', dotenv(encodedEnv), true)
+    await writeNew(
+      target,
+      '.env.test',
+      dotenv({
+        ...encodedEnv,
+        NODE_ENV: 'test',
+        PORT: testPort,
+        APP_URL: `http://127.0.0.1:${testPort}`,
+        APP_KEY: randomBytes(32).toString('base64url'),
+        DB_DATABASE: names.testDatabase,
+      }),
+      true
+    )
+    await writeNew(
+      target,
+      '.env.example',
+      dotenv({
+        ...encodedEnv,
+        APP_KEY: '',
+        DB_PASSWORD: '',
+        ...(profile.redis.password ? { REDIS_PASSWORD: '' } : {}),
+      })
+    )
+    const password = randomBytes(24).toString('base64url')
+    await writeNew(
+      target,
+      'tmp/dev-admin.txt',
+      `Local development administrator\nEmail: ${email}\nPassword: ${password}\n`,
+      true
+    )
+    await writeNew(
+      target,
+      'README.md',
+      `# ${name}\n\nCreated with @adula/create-app ${template.version}. Node.js 24+ is required.\n\n## Local development\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nOpen ${appEnv.APP_URL}. Administrator credentials are in ignored tmp/dev-admin.txt. After signing in, open /admin/setup and follow docs/initial-setup.md to review identity and verify service readiness.\nRun workers separately with node ace adula:worker, the outbox dispatcher with node ace adula:outbox, and the scheduler with node ace scheduler:run.\n\n${values.services === 'docker' ? 'PostgreSQL 17 and Redis 7 run in Docker. Start them with docker compose up -d --wait; stop with docker compose stop. Named volumes retain data; never use down -v unless deliberately deleting the local databases.' : 'PostgreSQL 17 and Redis use your existing services. Installation created fresh databases; keep .env and .env.test private.'}\n\n## Verification\n\nRun npm run typecheck, npm test, npm run lint and npm run build. Tests use the separate *_test database and a distinct Redis namespace.\n\n## Company identity\n\nRead docs/design-identity.md and the managed design skill before changing UI. Source files and shadcn components belong to this application.\n\n## External services and production\n\nLocal file storage is enabled. SMTP (including a local relay), OAuth provider credentials, S3, off-site backups, and production deployment need actual destination configuration. The creator does not enable unconfigured external services. Production requires backup variables validated in start/env.ts.\n\n## Incomplete installation\n\nReview the reported failing step; files and databases are retained. After resolving it, use npm exec --yes --package=pnpm@11.19.0 -- pnpm install, node ace migration:run, and node ace adula:setup. Setup reads tmp/dev-admin.txt; it refuses to promote an existing account with a different password. Then run node ace adula:doctor and npm run build. Never recreate over a nonempty directory.\n`
+    )
+    await writeNew(target, 'tmp/install.log', '', true)
+    const options = {
+      cwd: target,
+      env,
+      logFile: join(target, 'tmp/install.log'),
+    }
+    progress.start('Install AdonisJS, adula and UI dependencies')
+    await run(manager[0], [...manager.slice(1), 'install', '--prod=false'], options)
+    progress.start('Start services and create fresh databases')
+    if (values.services === 'docker') {
+      await writeNew(target, 'compose.yaml', composeFile())
+      await run(
+        'docker',
+        ['compose', '--env-file', '.env', 'up', '-d', '--wait', '--wait-timeout', '120'],
+        options
+      )
+      await pingRedis(profile.redis)
+    }
+    await createDatabases(profile.postgres, names)
+    progress.start('Apply migrations and configure administrator, UI and skills')
+    await run(process.execPath, ['ace', 'codegen'], options)
+    await run(process.execPath, ['ace', 'migration:run', '--force'], options)
+    await run(process.execPath, ['ace', 'adula:setup'], options)
+    const sourceFiles = [
+      ...Object.keys(template.files).filter((path) => /\.(?:ts|tsx|js|json|css)$/.test(path)),
+      'inertia/brand.ts',
+      'inertia/css/brand.css',
+    ]
+    await run(
+      manager[0],
+      [...manager.slice(1), 'exec', 'prettier', '--write', ...sourceFiles],
+      options
+    )
+    await run(process.execPath, ['ace', 'adula:doctor'], options)
+    progress.start('Typecheck and build the application')
+    await run(manager[0], [...manager.slice(1), 'run', 'typecheck'], options)
+    await run(manager[0], [...manager.slice(1), 'run', 'build'], options)
+    await writeNew(
+      target,
+      'adula-setup.json',
+      JSON.stringify(
+        {
+          version: template.version,
+          completed: true,
+          services: values.services,
+          database: names.database,
+          testDatabase: names.testDatabase,
+        },
+        null,
+        2
+      ) + '\n'
+    )
+    progress.finish()
+    console.log(
+      `\nYour application is ready: ${target}\nAdministrator credentials: tmp/dev-admin.txt\nInstallation log: tmp/install.log\nNext: cd "${target}"\n      npm run dev\nOpen: ${appEnv.APP_URL}\n`
+    )
+  } catch (error) {
+    progress.finish(true)
+    throw error
+  }
+}
+
+// npm bin entries are symlinks on Linux. Node resolves the imported module URL,
+// but argv retains the link path; compare their real paths before starting.
+if (process.argv[1] && import.meta.url === pathToFileURL(await realpath(process.argv[1])).href)
+  main().catch((error) => {
+    console.error(
+      `\nSetup did not complete: ${error.message}\nCreated files and databases are retained so you can inspect and resume setup.`
+    )
+    process.exitCode = 1
+  })

package/build/progress.mjs

@@ -0,0 +1,40 @@
+/** Portable terminal progress. Redirected output and NO_COLOR stay plain and stable. */
+export class Progress {
+  constructor(output = process.stdout, env = process.env) {
+    this.output = output
+    this.animated = Boolean(output.isTTY && !('NO_COLOR' in env) && env.TERM !== 'dumb')
+    this.index = 0
+    this.total = 6
+    this.timer = undefined
+    this.current = undefined
+  }
+
+  start(label) {
+    this.finish()
+    this.current = label
+    this.index += 1
+    this.started = Date.now()
+    let frame = 0
+    const draw = () =>
+      this.output.write(
+        `\r\x1b[2K\x1b[36m${['|', '/', '-', '\\'][frame++ % 4]} [${this.index}/${this.total}]\x1b[0m ${label} (${Math.floor((Date.now() - this.started) / 1000)}s)`
+      )
+    if (this.animated) {
+      draw()
+      this.timer = setInterval(draw, 100)
+      this.timer.unref()
+    } else this.output.write(`[${this.index}/${this.total}] ${label}\n`)
+  }
+
+  finish(failed = false) {
+    clearInterval(this.timer)
+    this.timer = undefined
+    if (!this.current) return
+    const prefix = this.animated ? `\r\x1b[2K\x1b[${failed ? '31' : '32'}m` : ''
+    const suffix = this.animated ? '\x1b[0m' : ''
+    this.output.write(
+      `${prefix}${failed ? 'FAIL' : 'OK'} [${this.index}/${this.total}] ${this.current}${suffix}\n`
+    )
+    this.current = undefined
+  }
+}

package/build/project.mjs

@@ -0,0 +1,237 @@
+import { lstat, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, relative, resolve, join } from 'node:path'
+
+export function projectName(target) {
+  const name = basename(resolve(target))
+  if (!/^[a-z][a-z0-9-]{0,49}$/.test(name))
+    throw new Error(
+      'Project directory name must start with a lowercase letter and use lowercase letters, digits or hyphens (up to 50 characters).'
+    )
+  return name
+}
+
+export async function assertEmpty(target) {
+  try {
+    const info = await lstat(target)
+    if (!info.isDirectory() || info.isSymbolicLink() || (await readdir(target)).length)
+      throw new Error(
+        'Project directory is nonempty or a symbolic link. Choose a new directory; existing files will not be overwritten.'
+      )
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+}
+
+export async function writeNew(root, path, text, secret = false) {
+  if (!path || path.includes('\\') || path.split('/').includes('..') || isAbsolute(path))
+    throw new Error('Unsafe template path.')
+  const dest = resolve(root, path)
+  const rel = relative(resolve(root), dest)
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) throw new Error('Unsafe template path.')
+  // Reject symlink parents as well as final symlinks; all writes use O_EXCL.
+  let parent = dirname(dest)
+  while (parent !== dirname(resolve(root))) {
+    try {
+      if ((await lstat(parent)).isSymbolicLink())
+        throw new Error('Cannot write through a symbolic link.')
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    }
+    if (parent === resolve(root)) break
+    parent = dirname(parent)
+  }
+  await mkdir(dirname(dest), { recursive: true })
+  await writeFile(dest, text, {
+    flag: 'wx',
+    ...(secret ? { mode: 0o600 } : {}),
+  })
+}
+
+export function dotenv(values) {
+  return (
+    Object.entries(values)
+      .map(([key, value]) => {
+        const text = String(value)
+        // Adonis interpolates dollars even inside quotes. Complex values are stored
+        // with its file: identifier by prepareEnvironment, preserving exact bytes.
+        if (/[\r\n\0'$\\]/.test(text))
+          throw new Error(
+            `Value for ${key} contains unsupported characters for direct environment encoding.`
+          )
+        return `${key}='${text}'`
+      })
+      .join('\n') + '\n'
+  )
+}
+
+export async function prepareEnvironment(target, values) {
+  const encoded = { ...values }
+  for (const [key, value] of Object.entries(values)) {
+    if (/[\r\n\0'$\\]/.test(String(value)) || String(value).startsWith('file:')) {
+      if (String(value).includes('\0')) throw new Error(`Invalid value for ${key}.`)
+      await writeNew(target, `tmp/env/${key}`, String(value), true)
+      encoded[key] = `file:./tmp/env/${key}`
+    }
+  }
+  return encoded
+}
+
+export function composeFile() {
+  return `services:
+  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_USER: adula
+      POSTGRES_PASSWORD: \${DB_PASSWORD}
+      POSTGRES_DB: postgres
+    ports: ["127.0.0.1:\${DB_PORT}:5432"]
+    volumes: ["postgres-data:/var/lib/postgresql/data"]
+    command: ["postgres", "-c", "shared_preload_libraries=pg_stat_statements"]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U adula -d postgres"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+  redis:
+    image: redis:7
+    ports: ["127.0.0.1:\${REDIS_PORT}:6379"]
+    volumes: ["redis-data:/data"]
+    command: ["redis-server", "--appendonly", "yes"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+volumes:
+  postgres-data:
+  redis-data:
+`
+}
+
+export async function readIdentity(file, company) {
+  const identity = file ? await readJson(resolve(file), 'identity') : {}
+  if (!identity || typeof identity !== 'object' || Array.isArray(identity))
+    throw new Error('Identity file must contain a JSON object.')
+  if (
+    Object.keys(identity).some(
+      (key) => !['primaryColor', 'fontFamily', 'logo', 'guidelines'].includes(key)
+    )
+  )
+    throw new Error('Identity file accepts only primaryColor, fontFamily, logo and guidelines.')
+  if (
+    typeof company !== 'string' ||
+    !company.trim() ||
+    company.length > 150 ||
+    /[\r\n\0]/.test(company)
+  )
+    throw new Error('Company name is required (up to 150 characters, without newlines).')
+  for (const key of ['primaryColor', 'fontFamily', 'logo', 'guidelines'])
+    if (identity[key] !== undefined && typeof identity[key] !== 'string')
+      throw new Error(`Identity field ${key} must be a string.`)
+  if (identity.primaryColor && !/^#[\da-fA-F]{6}$/.test(identity.primaryColor))
+    throw new Error('Brand color must be a hex color such as #14532d.')
+  if (identity.fontFamily && !/^[\p{L}\p{N} _,-]{1,100}$/u.test(identity.fontFamily))
+    throw new Error('Invalid font family.')
+  if (identity.logo) {
+    const path = resolve(dirname(resolve(file)), identity.logo)
+    if (!/\.(png|jpe?g|webp)$/i.test(path)) throw new Error('Use a local PNG, JPEG or WebP logo.')
+    const stat = await lstat(path)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 5 * 1024 * 1024)
+      throw new Error('Logo must be an image file up to 5 MB.')
+    identity.logoBytes = await readFile(path)
+    identity.logoPath = `/brand/logo.${path.split('.').at(-1).toLowerCase()}`
+  }
+  return { ...identity, company: company.trim() }
+}
+
+export async function readJson(file, label) {
+  const text = await readFile(file, 'utf8')
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`The ${label} file is not valid JSON. Review the file locally.`)
+  }
+}
+
+export function brandCss(identity) {
+  let css = '\n/* Company identity supplied during project creation. */\n'
+  if (identity.primaryColor) {
+    const channels = identity.primaryColor
+      .slice(1)
+      .match(/../g)
+      .map((hex) => parseInt(hex, 16) / 255)
+      .map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+    const luminance = channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722
+    const foreground = luminance > 0.179 ? '#000000' : '#ffffff'
+    css += `:root, .dark { --primary: ${identity.primaryColor}; --primary-foreground: ${foreground}; --ring: ${identity.primaryColor}; }\n`
+  }
+  if (identity.fontFamily)
+    css += `@theme { --font-sans: "${identity.fontFamily}", "Noto Sans Arabic", sans-serif; }\n`
+  return css
+}
+
+export async function renderProject(target, template, { name, identity, packageFiles }) {
+  const files = { ...template.files }
+  const pkg = JSON.parse(files['package.json'])
+  pkg.name = name
+  if (packageFiles) {
+    // Acceptance tests and offline releases can use reviewed local tarballs.
+    // They are copied into the new app, so no monorepo links survive.
+    for (const kind of ['kit', 'ui']) {
+      const archive = resolve(packageFiles, `adula-${kind}-${template.version}.tgz`)
+      await writeNew(target, `.adula-packages/adula-${kind}.tgz`, await readFile(archive))
+      pkg.dependencies[`@adula/${kind}`] = `file:.adula-packages/adula-${kind}.tgz`
+    }
+  }
+  files['package.json'] = JSON.stringify(pkg, null, 2) + '\n'
+  const brand = { company: identity.company, logo: identity.logoPath ?? null }
+  files['company-identity.json'] = JSON.stringify(brand, null, 2) + '\n'
+  files['inertia/brand.ts'] = `export const brand = ${JSON.stringify(brand, null, 2)}\n`
+  for (const path of [
+    'inertia/layouts/default.tsx',
+    'inertia/layouts/workspace.tsx',
+    'inertia/pages/home.tsx',
+  ]) {
+    files[path] = `import { brand } from '~/brand'\n` + files[path]
+  }
+  files['inertia/layouts/default.tsx'] = files['inertia/layouts/default.tsx']
+    .replace('aria-label="adula kit — الرئيسية"', 'aria-label={brand.company}')
+    .replace(
+      '<strong dir="ltr">adula kit</strong>',
+      '<strong>{brand.logo && <img src={brand.logo} alt="" className="inline-block size-8 object-contain" />} {brand.company}</strong>'
+    )
+  files['inertia/layouts/workspace.tsx'] = files['inertia/layouts/workspace.tsx']
+    .replaceAll('>عدولة<', '>{brand.company}<')
+    .replace('التطبيق المرجعي', '{brand.company}')
+    .replace(
+      '            ع\n',
+      '            {brand.logo ? <img src={brand.logo} alt="" className="size-10 object-contain" /> : brand.company.charAt(0)}\n'
+    )
+    .replace('text-white', 'text-primary-foreground')
+  files['inertia/pages/home.tsx'] = files['inertia/pages/home.tsx'].replace(
+    'title="مساحة العمل · adula kit"',
+    'title={brand.company}'
+  )
+  files['inertia/app.tsx'] =
+    `import { brand } from './brand'\n` +
+    files['inertia/app.tsx'].replace(
+      "import.meta.env.VITE_APP_NAME || 'adula kit'",
+      'brand.company'
+    )
+  files['docs/design-identity.md'] =
+    `# Company identity\n\nSource: project creator, supplied during installation.\n\n- Company: ${identity.company}\n- Logo: ${identity.logoPath ?? 'Pending; request it before further visual design.'}\n- Primary color: ${identity.primaryColor ?? 'Pending; existing kit colors are provisional.'}\n- Font: ${identity.fontFamily ?? 'Pending; Noto Sans Arabic is provisional.'}\n- Guidelines: ${identity.guidelines ?? 'Pending; request the company brand guide.'}\n\nUse the bundled adula-frontend-design skill for business interfaces. Keep shadcn/ui and Dialog defaults. A specified font must be licensed and installed locally or added as a project-owned asset; do not fetch unprovided fonts or branding.\n`
+  files['AGENTS.md'] =
+    '# Project rules\n\nRead docs/design-identity.md before visual design. Request only missing identity items. Application code and UI belong to this project; never edit installed @adula packages.\n'
+  for (const [path, contents] of Object.entries(files)) await writeNew(target, path, contents)
+  if (identity.logoBytes) await writeNew(target, `public${identity.logoPath}`, identity.logoBytes)
+  await writeNew(target, 'inertia/css/brand.css', brandCss(identity))
+  // Applied after the kit tokens, including after subsequent adula:ui upgrades.
+  const app = join(target, 'inertia/app.tsx')
+  await writeFile(
+    app,
+    (await readFile(app, 'utf8')).replace(
+      "import './css/kit.css'",
+      "import './css/kit.css'\nimport './css/brand.css'"
+    )
+  )
+}