@newlogic-digital/cli 1.4.0 → 1.5.0-next.1

package/index.mjs

@@ -2,6 +2,7 @@
 
 import init from './src/commands/init/index.mjs'
 import cms from './src/commands/cms/index.mjs'
+import blocks from './src/commands/blocks/index.mjs'
 import { styleText } from 'node:util'
 import { version, name } from './src/utils.mjs'
 
@@ -60,30 +61,42 @@ const command = rawArgs[0]
 
 if (!command) {
   console.log(`
-        ${styleText('blue', `${name} v${version}`)}
-        
-        Usage:
-        
-        -- init --
-        ${styleText('green', 'newlogic init')} - Creates a new project in current directory
-        ${styleText('green', 'newlogic init')} ${styleText('yellow', '<directory>')} - Creates a new project in new directory with the name ${styleText('yellow', '<directory>')}
-        ${styleText('green', 'newlogic init ui')} - Creates a new ${styleText('blue', '@newlogic-digital/ui')} project in current directory
-        ${styleText('green', 'newlogic init ui')} ${styleText('yellow', '<directory>')} - Creates a new ${styleText('blue', '@newlogic-digital/ui')} project in new directory with the name ${styleText('yellow', '<directory>')}
-        ${styleText('green', 'newlogic init cms')} - Creates a new ${styleText('blue', '@newlogic-digital/cms')} project in current directory
-        ${styleText('green', 'newlogic init cms')} ${styleText('yellow', '<directory>')} - Creates a new ${styleText('blue', '@newlogic-digital/cms')} project in new directory with the name ${styleText('yellow', '<directory>')}
-        ${styleText('green', 'newlogic init ui')} ${styleText('yellow', '<directory>')} ${styleText('cyan', '--branch=dev --clone=https --scope=blank --git --remote=<git-url> --install')}
-        ${styleText('green', 'newlogic init cms')} ${styleText('yellow', '<directory>')} ${styleText('cyan', '--branch=dev --clone=https --variant=cms-web --install --prepare --dev --migrations')}
-        ${styleText('green', 'newlogic init ui')} ${styleText('yellow', '<directory>')} ${styleText('cyan', '-y')} - Runs with default options without prompts
-        
-        -- cms --
-        ${styleText('green', 'newlogic cms prepare')} - Copies templates and components from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')}
-        ${styleText('green', 'newlogic cms prepare views')} - Copies views from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
-        ${styleText('green', 'newlogic cms prepare components')} - Copies components from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
-        ${styleText('green', 'newlogic cms new-component')} ${styleText('yellow', '<name>')} - Creates a new ${styleText('blue', '@newlogic-digital/cms')} section with name ${styleText('yellow', '<name>')}
-        ${styleText('red', 'newlogic cms prepare templates')} - (deprecated) Copies templates from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
-        ${styleText('red', 'newlogic cms prepare sections')} - (deprecated) Copies sections from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
-        ${styleText('red', 'newlogic cms new-section')} ${styleText('yellow', '<name>')} - (deprecated) Creates a new ${styleText('blue', '@newlogic-digital/cms')} section with name ${styleText('yellow', '<name>')}
-    `)
+    ${styleText('blue', `${name} v${version}`)}
+    
+    Usage:
+    
+    -- init --
+    ${styleText('green', 'newlogic init')} - Creates a new project in current directory
+    ${styleText('green', 'newlogic init')} ${styleText('yellow', '<directory>')} - Creates a new project in new directory with the name ${styleText('yellow', '<directory>')}
+    ${styleText('green', 'newlogic init ui')} - Creates a new ${styleText('blue', '@newlogic-digital/ui')} project in current directory
+    ${styleText('green', 'newlogic init ui')} ${styleText('yellow', '<directory>')} - Creates a new ${styleText('blue', '@newlogic-digital/ui')} project in new directory with the name ${styleText('yellow', '<directory>')}
+    ${styleText('green', 'newlogic init cms')} - Creates a new ${styleText('blue', '@newlogic-digital/cms')} project in current directory
+    ${styleText('green', 'newlogic init cms')} ${styleText('yellow', '<directory>')} - Creates a new ${styleText('blue', '@newlogic-digital/cms')} project in new directory with the name ${styleText('yellow', '<directory>')}
+    ${styleText('green', 'newlogic init ui')} ${styleText('yellow', '<directory>')} ${styleText('cyan', '--branch=dev --clone=https --scope=blank --git --remote=<git-url> --install')}
+    ${styleText('green', 'newlogic init cms')} ${styleText('yellow', '<directory>')} ${styleText('cyan', '--branch=dev --clone=https --variant=cms-web --install --prepare --dev --migrations')}
+    ${styleText('green', 'newlogic init ui')} ${styleText('yellow', '<directory>')} ${styleText('cyan', '-y')} - Runs with default options without prompts
+    
+    -- cms --
+    ${styleText('green', 'newlogic cms prepare')} - Copies templates and components from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')}
+    ${styleText('green', 'newlogic cms prepare views')} - Copies views from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
+    ${styleText('green', 'newlogic cms prepare components')} - Copies components from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
+    ${styleText('green', 'newlogic cms new-component')} ${styleText('yellow', '<name>')} - Creates a new ${styleText('blue', '@newlogic-digital/cms')} section with name ${styleText('yellow', '<name>')}
+    ${styleText('red', 'newlogic cms prepare templates')} - (deprecated) Copies templates from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
+    ${styleText('red', 'newlogic cms prepare sections')} - (deprecated) Copies sections from ${styleText('blue', '@newlogic-digital/ui')} project to ${styleText('blue', '@newlogic-digital/cms')} even if they already exists
+    ${styleText('red', 'newlogic cms new-section')} ${styleText('yellow', '<name>')} - (deprecated) Creates a new ${styleText('blue', '@newlogic-digital/cms')} section with name ${styleText('yellow', '<name>')}
+  
+    -- blocks --
+    ${styleText('green', 'newlogic blocks list')} - Lists all available installable blocks with descriptions
+    ${styleText('green', 'newlogic blocks add')} ${styleText('yellow', '<name...>')} - Installs one or more blocks by kebab-case or PascalCase name
+    ${styleText('green', 'newlogic blocks remove')} ${styleText('yellow', '<name...>')} - Removes one or more blocks and orphaned dependencies
+    ${styleText('green', 'newlogic blocks update')} - Reinstalls all configured blocks from ${styleText('yellow', 'newlogic.config.json')}
+    ${styleText('green', 'newlogic blocks add')} ${styleText('yellow', 'about-accordion')}
+    ${styleText('green', 'newlogic blocks add')} ${styleText('yellow', 'AboutAccordion')}
+    ${styleText('green', 'newlogic blocks add')} ${styleText('yellow', 'header-nav-left contact-info-card hero-floating-text')}
+    ${styleText('green', 'newlogic blocks remove')} ${styleText('yellow', 'about-accordion')}
+    ${styleText('green', 'newlogic blocks remove')} ${styleText('yellow', 'header-nav-left hero-floating-text')}
+    ${styleText('green', 'newlogic blocks update')}
+  `)
 }
 
 if (command === 'init') {
@@ -101,3 +114,11 @@ if (command === 'cms') {
 
   await cms(action, name)
 }
+
+if (command === 'blocks') {
+  const { positionals } = parseCommandArgs(rawArgs.slice(1))
+  const action = positionals[0]
+  const names = positionals.slice(1)
+
+  await blocks(action, names)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newlogic-digital/cli",
-  "version": "1.4.0",
+  "version": "1.5.0-next.1",
   "main": "index.mjs",
   "bin": {
     "newlogic-cli": "index.mjs",
@@ -8,10 +8,13 @@
   },
   "scripts": {
     "oxlint": "oxlint",
-    "oxlint-fix": "oxlint --fix"
+    "oxlint-fix": "oxlint --fix",
+    "test": "node --test",
+    "publish-next": "npm publish --tag next"
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
+    "ajv": "^8.17.1",
     "dedent": "^1.7.2",
     "es-toolkit": "^1.45.1",
     "fast-glob": "^3.3.3",

package/src/commands/blocks/index.mjs

@@ -0,0 +1,195 @@
+import { styleText } from 'node:util'
+import { createBlocksService } from './service.mjs'
+
+function label(color, text) {
+  return styleText([color, 'bold'], text)
+}
+
+function highlightQuoted(text) {
+  return text.replace(/"([^"]+)"/g, (_, value) => styleText(['yellow', 'bold'], `"${value}"`))
+}
+
+function highlightTokens(text) {
+  return highlightQuoted(text)
+    .replaceAll('newlogic.config.json', styleText(['yellow', 'bold'], 'newlogic.config.json'))
+    .replaceAll('composer.json', styleText(['yellow', 'bold'], 'composer.json'))
+    .replaceAll('package.json', styleText(['yellow', 'bold'], 'package.json'))
+    .replaceAll('sharedFiles', styleText(['magenta', 'bold'], 'sharedFiles'))
+    .replace(/\bcomposer\b/g, styleText(['blue', 'bold'], 'composer'))
+    .replace(/\bnpm\b/g, styleText(['blue', 'bold'], 'npm'))
+}
+
+function formatErrorMessage(message) {
+  let nextMessage = highlightTokens(message)
+
+  if (nextMessage.startsWith('Command failed: ')) {
+    nextMessage = `Command failed: ${styleText(['red', 'bold'], nextMessage.slice(16))}`
+  }
+
+  if (nextMessage.startsWith('Request failed for ')) {
+    nextMessage = nextMessage.replace(
+      /^Request failed for ([^(]+) \((.+)\)$/,
+      (_, url, status) => `Request failed for ${styleText('cyan', url.trim())} ${styleText(['red', 'bold'], `(${status})`)}`,
+    )
+  }
+
+  return nextMessage
+}
+
+function createSilentLogger() {
+  return {
+    info() {},
+    warn() {},
+  }
+}
+
+function formatInfoMessage(message) {
+  if (message.startsWith('install ')) {
+    return `${label('cyan', 'install')} ${styleText(['white', 'bold'], message.slice(8))}`
+  }
+
+  if (message.startsWith('remove ')) {
+    return `${label('cyan', 'remove')} ${styleText(['white', 'bold'], message.slice(7))}`
+  }
+
+  if (message.startsWith('write ')) {
+    return `  ${label('green', 'write')} ${styleText('white', message.slice(6))}`
+  }
+
+  if (message.startsWith('delete ')) {
+    return `  ${label('red', 'delete')} ${styleText('white', message.slice(7))}`
+  }
+
+  if (message.startsWith('skip missing ')) {
+    return `  ${label('yellow', 'skip')} ${styleText('dim', message.slice(13))} ${styleText('dim', '(missing)')}`
+  }
+
+  if (message.startsWith('skip ')) {
+    return `  ${label('yellow', 'skip')} ${styleText('dim', message.slice(5))}`
+  }
+
+  if (message.startsWith('composer require ')) {
+    return `${label('blue', 'composer')} ${styleText(['white', 'bold'], message.slice(17))}`
+  }
+
+  if (message.startsWith('npm install ')) {
+    return `${label('blue', 'npm')} ${styleText(['white', 'bold'], message.slice(12))}`
+  }
+
+  if (message.startsWith('postInstall ')) {
+    return `${label('magenta', 'hook')} ${styleText(['white', 'bold'], message.slice(12))}`
+  }
+
+  if (message.startsWith('added ')) {
+    return `${label('green', 'done')} ${styleText(['white', 'bold'], message.slice(6))}`
+  }
+
+  if (message.startsWith('removed ')) {
+    return `${label('green', 'done')} ${styleText(['white', 'bold'], message.slice(8))}`
+  }
+
+  if (message.startsWith('updated ')) {
+    return `${label('green', 'done')} ${styleText(['white', 'bold'], message.slice(8))}`
+  }
+
+  if (message.startsWith('No blocks configured')) {
+    return `${label('yellow', 'info')} ${styleText('yellow', message)}`
+  }
+
+  return `${label('gray', 'info')} ${highlightTokens(message)}`
+}
+
+function createCliLogger() {
+  return {
+    info(message) {
+      console.log(formatInfoMessage(message))
+    },
+
+    warn(message) {
+      console.log(`${label('yellow', 'warn')} ${styleText('yellow', highlightTokens(message))}`)
+    },
+  }
+}
+
+function printBlocksList(blocks) {
+  const width = blocks.reduce((maxWidth, block) => Math.max(maxWidth, block.name.length), 0)
+
+  console.log(`${styleText(['blue', 'bold'], 'Available Blocks')} ${styleText('dim', `(${blocks.length})`)}`)
+  console.log('')
+
+  for (const block of blocks) {
+    const name = styleText(['green', 'bold'], block.name.padEnd(width))
+    const description = block.description
+      ? styleText('dim', block.description)
+      : styleText('dim', 'No description')
+
+    console.log(`  ${name}  ${description}`)
+  }
+}
+
+function printBlocksUsage() {
+  console.log([
+    styleText(['blue', 'bold'], 'newlogic blocks'),
+    '',
+    styleText(['white', 'bold'], 'Usage:'),
+    '',
+    `  ${styleText('green', 'newlogic blocks list')} - Lists all available blocks with descriptions`,
+    `  ${styleText('green', 'newlogic blocks add')} ${styleText('yellow', '<name...>')} - Adds one or more blocks by kebab-case or PascalCase name`,
+    `  ${styleText('green', 'newlogic blocks remove')} ${styleText('yellow', '<name...>')} - Removes one or more blocks and orphaned dependencies`,
+    `  ${styleText('green', 'newlogic blocks update')} - Reinstalls all configured blocks from ${styleText('yellow', 'newlogic.config.json')}`,
+    '',
+    styleText(['white', 'bold'], 'Examples:'),
+    '',
+    `  ${styleText('green', 'newlogic blocks add')} ${styleText('yellow', 'header-nav-left contact-info-card hero-floating-text')}`,
+    `  ${styleText('green', 'newlogic blocks remove')} ${styleText('yellow', 'header-nav-left hero-floating-text')}`,
+  ].join('\n'))
+}
+
+export default async function blocks(action, names = []) {
+  if (!action || action === 'help' || action === '--help') {
+    printBlocksUsage()
+    return
+  }
+
+  try {
+    if (action === 'list') {
+      const service = createBlocksService({ logger: createSilentLogger() })
+      const entries = await service.listBlocks()
+
+      printBlocksList(entries)
+      return
+    }
+
+    if (action === 'add') {
+      if (names.length === 0) {
+        throw new Error('Missing block name for "newlogic blocks add"')
+      }
+
+      const service = createBlocksService({ logger: createCliLogger() })
+      await service.addBlocks(names)
+      return
+    }
+
+    if (action === 'remove') {
+      if (names.length === 0) {
+        throw new Error('Missing block name for "newlogic blocks remove"')
+      }
+
+      const service = createBlocksService({ logger: createCliLogger() })
+      await service.removeBlocks(names)
+      return
+    }
+
+    if (action === 'update') {
+      const service = createBlocksService({ logger: createCliLogger() })
+      await service.updateBlocks()
+      return
+    }
+
+    throw new Error(`Unknown blocks action "${action}"`)
+  }
+  catch (error) {
+    console.log(`${label('red', 'error')} ${formatErrorMessage(error.message)}`)
+    process.exit(1)
+  }
+}

package/src/commands/blocks/repository.mjs

@@ -0,0 +1,126 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { resolveInside } from '../../utils.mjs'
+
+const DEFAULT_REMOTE_SOURCE_BASE_URL = 'https://git.newlogic.cz/newlogic-digital/newlogic-blocks/-/raw/main/src'
+
+function encodePath(relativePath) {
+  return relativePath
+    .split('/')
+    .filter(Boolean)
+    .map(segment => encodeURIComponent(segment))
+    .join('/')
+}
+
+function buildRemoteUrl(baseUrl, relativePath) {
+  return `${baseUrl}/${encodePath(relativePath)}`
+}
+
+async function fetchOrThrow(fetchImpl, url) {
+  const response = await fetchImpl(url)
+
+  if (!response.ok) {
+    throw new Error(`Request failed for ${url} (${response.status} ${response.statusText})`)
+  }
+
+  return response
+}
+
+async function fetchJson(fetchImpl, url) {
+  const response = await fetchOrThrow(fetchImpl, url)
+
+  try {
+    return await response.json()
+  }
+  catch (error) {
+    throw new Error(`Invalid JSON returned from ${url}: ${error.message}`)
+  }
+}
+
+async function fetchBuffer(fetchImpl, url) {
+  const response = await fetchOrThrow(fetchImpl, url)
+  const arrayBuffer = await response.arrayBuffer()
+
+  return Buffer.from(arrayBuffer)
+}
+
+function buildGeneratedIndex(componentsRoot) {
+  const blocks = fs.readdirSync(componentsRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .filter(name => fs.existsSync(path.join(componentsRoot, name, 'meta.json')))
+    .map((name) => {
+      const metaPath = path.join(componentsRoot, name, 'meta.json')
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'))
+
+      return {
+        name: meta.name,
+        description: meta.description ?? '',
+      }
+    })
+
+  return { blocks }
+}
+
+export function createRemoteBlocksRepository({ baseUrl = DEFAULT_REMOTE_SOURCE_BASE_URL, fetchImpl = fetch } = {}) {
+  return {
+    async getSchema() {
+      return await fetchJson(fetchImpl, buildRemoteUrl(baseUrl, 'schema.json'))
+    },
+
+    async getIndex() {
+      return await fetchJson(fetchImpl, buildRemoteUrl(baseUrl, 'index.json'))
+    },
+
+    async getMeta(name) {
+      return await fetchJson(fetchImpl, buildRemoteUrl(baseUrl, `components/${name}/meta.json`))
+    },
+
+    async getFileBuffer(name, sourcePath) {
+      return await fetchBuffer(fetchImpl, buildRemoteUrl(baseUrl, `components/${name}/${sourcePath}`))
+    },
+  }
+}
+
+export function createFilesystemBlocksRepository({ rootDir }) {
+  const sourceRoot = path.resolve(rootDir, 'src')
+  const componentsRoot = path.join(sourceRoot, 'components')
+
+  return {
+    async getSchema() {
+      const schemaPath = resolveInside(sourceRoot, 'schema.json')
+
+      return JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+    },
+
+    async getIndex() {
+      const indexPath = path.join(sourceRoot, 'index.json')
+
+      if (fs.existsSync(indexPath)) {
+        return JSON.parse(fs.readFileSync(indexPath, 'utf8'))
+      }
+
+      return buildGeneratedIndex(componentsRoot)
+    },
+
+    async getMeta(name) {
+      const metaPath = resolveInside(componentsRoot, name, 'meta.json')
+
+      if (!fs.existsSync(metaPath)) {
+        throw new Error(`Missing meta.json for block "${name}" in ${componentsRoot}`)
+      }
+
+      return JSON.parse(fs.readFileSync(metaPath, 'utf8'))
+    },
+
+    async getFileBuffer(name, sourcePath) {
+      const filePath = resolveInside(componentsRoot, name, ...sourcePath.split('/'))
+
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Missing source file for block "${name}": ${sourcePath}`)
+      }
+
+      return fs.readFileSync(filePath)
+    },
+  }
+}

package/src/commands/blocks/service.mjs

@@ -0,0 +1,587 @@
+import childProcess from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import Ajv2020 from 'ajv/dist/2020.js'
+import fse from 'fs-extra'
+import { resolveInside } from '../../utils.mjs'
+import { createRemoteBlocksRepository } from './repository.mjs'
+
+const CONFIG_FILE_NAME = 'newlogic.config.json'
+const BLOCK_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function defaultLogger() {
+  return {
+    info: message => console.log(message),
+    warn: message => console.warn(message),
+  }
+}
+
+function runOrThrow(command, args, options = {}) {
+  const result = childProcess.spawnSync(command, args, {
+    cwd: options.cwd,
+    stdio: 'inherit',
+  })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(' ')}`)
+  }
+}
+
+function shellOrThrow(command, options = {}) {
+  const shell = process.env.SHELL || '/bin/sh'
+  const result = childProcess.spawnSync(shell, ['-lc', command], {
+    cwd: options.cwd,
+    stdio: 'inherit',
+  })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${command}`)
+  }
+}
+
+function createDefaultCommandRunner(projectRoot) {
+  return {
+    async runComposerRequire(packages) {
+      runOrThrow('composer', ['require', ...packages], { cwd: projectRoot })
+    },
+
+    async runNpmInstall(packages) {
+      runOrThrow('npm', ['install', ...packages], { cwd: projectRoot })
+    },
+
+    async runPostInstallCommand(command) {
+      shellOrThrow(command, { cwd: projectRoot })
+    },
+  }
+}
+
+function normalizeBlockName(value) {
+  const trimmed = `${value ?? ''}`.trim()
+
+  if (!trimmed) {
+    return ''
+  }
+
+  return trimmed
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+    .toLowerCase()
+}
+
+function assertBlockName(name, label = 'block name') {
+  if (!BLOCK_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid ${label}: "${name}"`)
+  }
+}
+
+function toBlockKey(block) {
+  return `${block.name}@${block.variant}`
+}
+
+function resolveTargetPath(projectRoot, rule) {
+  const destinationRoot = resolveInside(projectRoot, rule.destination)
+  const parentDirectory = rule.parentDirectory ? rule.parentDirectory.split('/').filter(Boolean) : []
+
+  return resolveInside(destinationRoot, ...parentDirectory, rule.fileName)
+}
+
+function cleanupEmptyDirectories(startDir, stopDir) {
+  let currentDir = startDir
+  const stopPath = path.resolve(stopDir)
+
+  while (currentDir.startsWith(stopPath) && currentDir !== stopPath) {
+    if (!fs.existsSync(currentDir)) {
+      currentDir = path.dirname(currentDir)
+      continue
+    }
+
+    const stat = fs.lstatSync(currentDir)
+
+    if (!stat.isDirectory()) {
+      currentDir = path.dirname(currentDir)
+      continue
+    }
+
+    if (fs.readdirSync(currentDir).length > 0) {
+      break
+    }
+
+    fs.rmdirSync(currentDir)
+    currentDir = path.dirname(currentDir)
+  }
+}
+
+function loadProjectConfig(projectRoot) {
+  const configPath = path.join(projectRoot, CONFIG_FILE_NAME)
+
+  if (!fs.existsSync(configPath)) {
+    return {
+      configPath,
+      config: { blocks: [] },
+      blocks: [],
+    }
+  }
+
+  let config
+
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  }
+  catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE_NAME}: ${error.message}`)
+  }
+
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`${CONFIG_FILE_NAME} must contain a JSON object`)
+  }
+
+  const blocksRaw = config.blocks ?? []
+
+  if (!Array.isArray(blocksRaw)) {
+    throw new Error(`"${CONFIG_FILE_NAME}" field "blocks" must be an array`)
+  }
+
+  const blocks = blocksRaw.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`Invalid block config entry at index ${index}`)
+    }
+
+    const name = normalizeBlockName(entry.name)
+    const variant = `${entry.variant ?? ''}`.trim()
+
+    assertBlockName(name, 'configured block name')
+
+    if (!variant) {
+      throw new Error(`Configured block "${name}" is missing a variant`)
+    }
+
+    return { name, variant }
+  })
+
+  return { configPath, config, blocks: dedupeExplicitBlocks(blocks) }
+}
+
+function saveProjectConfig(configPath, config, blocks) {
+  const nextConfig = {
+    ...config,
+    blocks,
+  }
+
+  fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`)
+}
+
+function dedupeExplicitBlocks(blocks) {
+  const byName = new Map()
+
+  for (const block of blocks) {
+    byName.set(block.name, block)
+  }
+
+  return [...byName.values()]
+}
+
+function normalizeRequestedBlockNames(rawNames, label = 'block name') {
+  if (!Array.isArray(rawNames) || rawNames.length === 0) {
+    throw new Error(`Missing ${label}`)
+  }
+
+  const normalizedNames = rawNames.map((rawName) => {
+    const name = normalizeBlockName(rawName)
+
+    assertBlockName(name, label)
+
+    return name
+  })
+
+  return [...new Set(normalizedNames)]
+}
+
+async function createMetaValidator(repository) {
+  const schema = await repository.getSchema()
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: false,
+    validateFormats: false,
+  })
+  const validate = ajv.compile(schema)
+
+  return (meta, sourceLabel) => {
+    const valid = validate(meta)
+
+    if (valid) {
+      return
+    }
+
+    const issues = (validate.errors ?? [])
+      .map((error) => {
+        const location = error.instancePath || '/'
+        return `${location} ${error.message}`.trim()
+      })
+      .join('; ')
+
+    throw new Error(`Invalid metadata for ${sourceLabel}: ${issues}`)
+  }
+}
+
+function ensureIndex(index) {
+  if (!index || typeof index !== 'object' || Array.isArray(index)) {
+    throw new Error('Invalid blocks index payload')
+  }
+
+  if (!Array.isArray(index.blocks)) {
+    throw new Error('Invalid blocks index payload: missing "blocks" array')
+  }
+
+  return index.blocks.map((block, indexPosition) => {
+    if (!block || typeof block !== 'object' || Array.isArray(block)) {
+      throw new Error(`Invalid block index entry at position ${indexPosition}`)
+    }
+
+    const name = normalizeBlockName(block.name)
+    const description = `${block.description ?? ''}`.trim()
+
+    assertBlockName(name)
+
+    return { name, description }
+  })
+}
+
+export function createBlocksService({
+  projectRoot = process.cwd(),
+  repository = createRemoteBlocksRepository(),
+  commandRunner = createDefaultCommandRunner(projectRoot),
+  logger = defaultLogger(),
+} = {}) {
+  const metaCache = new Map()
+  let validatorPromise
+
+  async function validateMeta(meta, sourceLabel) {
+    validatorPromise ||= createMetaValidator(repository)
+    const validator = await validatorPromise
+
+    validator(meta, sourceLabel)
+  }
+
+  async function getMeta(name) {
+    const normalizedName = normalizeBlockName(name)
+
+    assertBlockName(normalizedName)
+
+    if (!metaCache.has(normalizedName)) {
+      const meta = await repository.getMeta(normalizedName)
+      await validateMeta(meta, `block "${normalizedName}"`)
+      metaCache.set(normalizedName, meta)
+    }
+
+    return metaCache.get(normalizedName)
+  }
+
+  async function resolveInstallPlan(rootBlocks) {
+    const visited = new Set()
+    const resolving = new Set()
+    const plan = []
+
+    async function visit(name, preferredVariant) {
+      const normalizedName = normalizeBlockName(name)
+      const meta = await getMeta(normalizedName)
+      const variantName = preferredVariant || meta.install.defaultVariant
+      const variant = meta.install?.variants?.[variantName]
+
+      if (!variant) {
+        throw new Error(`Variant "${variantName}" is not available for block "${normalizedName}"`)
+      }
+
+      const key = toBlockKey({ name: normalizedName, variant: variantName })
+
+      if (visited.has(key)) {
+        return
+      }
+
+      if (resolving.has(key)) {
+        throw new Error(`Dependency cycle detected at "${key}"`)
+      }
+
+      resolving.add(key)
+
+      for (const dependency of variant.dependencies?.components ?? []) {
+        await visit(dependency.name, dependency.variant || variantName)
+      }
+
+      resolving.delete(key)
+      visited.add(key)
+      plan.push({
+        name: normalizedName,
+        variant: variantName,
+        meta,
+        installVariant: variant,
+      })
+    }
+
+    for (const block of rootBlocks) {
+      await visit(block.name, block.variant)
+    }
+
+    return plan
+  }
+
+  function summarizePlan(plan) {
+    const composer = new Set()
+    const npm = new Set()
+    const postInstall = []
+    const warnings = []
+
+    for (const item of plan) {
+      const sharedFiles = item.meta.install.sharedFiles ?? []
+
+      if (sharedFiles.length > 0) {
+        warnings.push(`Block "${item.name}" contains ${sharedFiles.length} sharedFiles entries. raw-only mode does not install them yet, skipping.`)
+      }
+
+      for (const dependency of item.installVariant.dependencies?.composer ?? []) {
+        composer.add(dependency)
+      }
+
+      for (const dependency of item.installVariant.dependencies?.npm ?? []) {
+        npm.add(dependency)
+      }
+
+      for (const step of item.installVariant.postInstall ?? []) {
+        postInstall.push({
+          blockName: item.name,
+          step,
+        })
+      }
+    }
+
+    return {
+      composer: [...composer],
+      npm: [...npm],
+      postInstall,
+      warnings,
+    }
+  }
+
+  function validateProjectDependencies(summary) {
+    if (summary.composer.length > 0 && !fs.existsSync(path.join(projectRoot, 'composer.json'))) {
+      throw new Error('composer dependencies are required by blocks metadata, but composer.json is missing in the current project')
+    }
+
+    if (summary.npm.length > 0 && !fs.existsSync(path.join(projectRoot, 'package.json'))) {
+      throw new Error('npm dependencies are required by blocks metadata, but package.json is missing in the current project')
+    }
+  }
+
+  async function installFile(blockName, rule) {
+    const whenExists = rule.whenExists || 'fail'
+    const targetPath = resolveTargetPath(projectRoot, rule)
+    const relativeTargetPath = path.relative(projectRoot, targetPath) || path.basename(targetPath)
+
+    if (fs.existsSync(targetPath)) {
+      if (whenExists === 'skip') {
+        logger.info(`skip ${relativeTargetPath}`)
+        return
+      }
+
+      if (whenExists === 'fail') {
+        throw new Error(`Cannot install block "${blockName}": target already exists (${relativeTargetPath})`)
+      }
+
+      if (whenExists === 'overwrite') {
+        fse.removeSync(targetPath)
+      }
+    }
+
+    const contents = await repository.getFileBuffer(blockName, rule.source)
+
+    fse.ensureDirSync(path.dirname(targetPath))
+    fs.writeFileSync(targetPath, contents)
+    logger.info(`write ${relativeTargetPath}`)
+  }
+
+  async function installPlan(plan) {
+    const summary = summarizePlan(plan)
+
+    validateProjectDependencies(summary)
+
+    for (const warning of summary.warnings) {
+      logger.warn(warning)
+    }
+
+    for (const item of plan) {
+      logger.info(`install ${item.name}@${item.variant}`)
+
+      for (const rule of item.installVariant.files ?? []) {
+        await installFile(item.name, rule)
+      }
+    }
+
+    if (summary.composer.length > 0) {
+      logger.info(`composer require ${summary.composer.join(' ')}`)
+      await commandRunner.runComposerRequire(summary.composer)
+    }
+
+    if (summary.npm.length > 0) {
+      logger.info(`npm install ${summary.npm.join(' ')}`)
+      await commandRunner.runNpmInstall(summary.npm)
+    }
+
+    for (const entry of summary.postInstall) {
+      if (entry.step.type === 'info') {
+        logger.info(entry.step.value)
+        continue
+      }
+
+      logger.info(`postInstall ${entry.blockName}: ${entry.step.value}`)
+      await commandRunner.runPostInstallCommand(entry.step.value)
+    }
+  }
+
+  async function removePlanItems(items) {
+    for (const item of [...items].reverse()) {
+      logger.info(`remove ${item.name}@${item.variant}`)
+
+      for (const rule of item.installVariant.files ?? []) {
+        const targetPath = resolveTargetPath(projectRoot, rule)
+        const relativeTargetPath = path.relative(projectRoot, targetPath) || path.basename(targetPath)
+
+        if (!fs.existsSync(targetPath)) {
+          logger.info(`skip missing ${relativeTargetPath}`)
+          continue
+        }
+
+        fse.removeSync(targetPath)
+        cleanupEmptyDirectories(path.dirname(targetPath), projectRoot)
+        logger.info(`delete ${relativeTargetPath}`)
+      }
+    }
+  }
+
+  async function listBlocks() {
+    const index = await repository.getIndex()
+    const blocks = ensureIndex(index)
+      .sort((left, right) => left.name.localeCompare(right.name))
+
+    for (const block of blocks) {
+      logger.info(`${block.name} - ${block.description}`)
+    }
+
+    return blocks
+  }
+
+  async function addBlock(rawName) {
+    const result = await addBlocks([rawName])
+
+    return {
+      block: result.blocks[0],
+      plan: result.plan,
+      configBlocks: result.configBlocks,
+    }
+  }
+
+  async function addBlocks(rawNames) {
+    const names = normalizeRequestedBlockNames(rawNames)
+    const rootBlocks = []
+
+    for (const name of names) {
+      const meta = await getMeta(name)
+
+      rootBlocks.push({
+        name,
+        variant: meta.install.defaultVariant,
+      })
+    }
+
+    const plan = await resolveInstallPlan(rootBlocks)
+
+    await installPlan(plan)
+
+    const { configPath, config, blocks } = loadProjectConfig(projectRoot)
+    const nextBlocks = dedupeExplicitBlocks([
+      ...blocks.filter(block => !names.includes(block.name)),
+      ...rootBlocks,
+    ])
+
+    saveProjectConfig(configPath, config, nextBlocks)
+    logger.info(`added ${rootBlocks.map(block => `${block.name}@${block.variant}`).join(', ')}`)
+
+    return {
+      blocks: rootBlocks,
+      plan,
+      configBlocks: nextBlocks,
+    }
+  }
+
+  async function removeBlock(rawName) {
+    const result = await removeBlocks([rawName])
+
+    return {
+      removed: result.removed,
+      configBlocks: result.configBlocks,
+    }
+  }
+
+  async function removeBlocks(rawNames) {
+    const names = normalizeRequestedBlockNames(rawNames)
+    const { configPath, config, blocks } = loadProjectConfig(projectRoot)
+    const missingNames = names.filter(name => !blocks.some(block => block.name === name))
+
+    if (missingNames.length > 0) {
+      const suffix = missingNames.length === 1 ? 'is' : 'are'
+      throw new Error(`Block${missingNames.length === 1 ? '' : 's'} "${missingNames.join('", "')}" ${suffix} not installed in ${CONFIG_FILE_NAME}`)
+    }
+
+    const beforePlan = await resolveInstallPlan(blocks)
+    const remainingBlocks = blocks.filter(block => !names.includes(block.name))
+    const afterPlan = remainingBlocks.length > 0 ? await resolveInstallPlan(remainingBlocks) : []
+    const afterKeys = new Set(afterPlan.map(toBlockKey))
+    const removedItems = beforePlan.filter(item => !afterKeys.has(toBlockKey(item)))
+
+    await removePlanItems(removedItems)
+    saveProjectConfig(configPath, config, remainingBlocks)
+    logger.info(`removed ${names.join(', ')}`)
+
+    return {
+      removed: removedItems,
+      configBlocks: remainingBlocks,
+    }
+  }
+
+  async function updateBlocks() {
+    const { blocks } = loadProjectConfig(projectRoot)
+
+    if (blocks.length === 0) {
+      logger.info(`No blocks configured in ${CONFIG_FILE_NAME}`)
+      return {
+        plan: [],
+      }
+    }
+
+    const plan = await resolveInstallPlan(blocks)
+
+    await installPlan(plan)
+    logger.info(`updated ${blocks.length} explicit block(s)`)
+
+    return { plan }
+  }
+
+  return {
+    addBlock,
+    addBlocks,
+    listBlocks,
+    removeBlock,
+    removeBlocks,
+    resolveInstallPlan,
+    updateBlocks,
+  }
+}
+
+export { normalizeBlockName }

package/src/commands/init/ui.mjs

@@ -4,6 +4,37 @@ import fse from 'fs-extra'
 import { join, resolve } from 'path'
 import { isAutoYes, normalizeEnum, normalizeYesNo } from './options.mjs'
 
+function replaceInFile(path, searchValue, replaceValue) {
+  if (!fse.existsSync(path)) {
+    return
+  }
+
+  const content = fse.readFileSync(path, 'utf8')
+  fse.writeFileSync(path, content.replace(searchValue, replaceValue))
+}
+
+function updateBlankPackageJson(path) {
+  if (!fse.existsSync(path)) {
+    return
+  }
+
+  const packageJson = JSON.parse(fse.readFileSync(path, 'utf8'))
+  const originalDependencies = (packageJson.dependencies && typeof packageJson.dependencies === 'object')
+    ? packageJson.dependencies
+    : {}
+
+  if (packageJson.scripts && typeof packageJson.scripts === 'object') {
+    delete packageJson.scripts['build-emails']
+  }
+
+  packageJson.dependencies = Object.fromEntries(
+    ['@newlogic-digital/utils-js', 'winduum']
+      .flatMap(name => Object.hasOwn(originalDependencies, name) ? [[name, originalDependencies[name]]] : []),
+  )
+
+  fse.writeFileSync(path, `${JSON.stringify(packageJson, null, 2)}\n`)
+}
+
 function prepareBlankInstall(projectPath) {
   [
     join(projectPath, 'src', 'template', 'emails'),
@@ -14,12 +45,9 @@ function prepareBlankInstall(projectPath) {
     join(projectPath, 'src', 'styles', 'tinymce.css'),
   ].forEach(path => fse.removeSync(path))
 
-  const mainDataPath = join(projectPath, 'src', 'data', 'main.json')
-
-  if (fse.existsSync(mainDataPath)) {
-    const mainData = fse.readFileSync(mainDataPath, 'utf8').replace('"cookieConsent": true', '"cookieConsent": false')
-    fse.writeFileSync(mainDataPath, mainData)
-  }
+  replaceInFile(join(projectPath, 'src', 'data', 'main.json'), '"cookieConsent": true', '"cookieConsent": false')
+  replaceInFile(join(projectPath, 'src', 'templates', 'layouts', 'default.latte'), '<body data-controller="x-app invoke" data-naja-snippet-append>', '<body>')
+  updateBlankPackageJson(join(projectPath, 'package.json'))
 
   const iconsPath = join(projectPath, 'src', 'icons')
   fse.ensureDirSync(iconsPath)

package/src/utils.mjs

@@ -1,9 +1,9 @@
 import childProcess from 'child_process'
 import fs from 'fs'
-import { dirname, resolve } from 'path'
+import path from 'path'
 import { fileURLToPath } from 'url'
 
-const { version, name } = JSON.parse(fs.readFileSync(resolve(dirname((fileURLToPath(import.meta.url))), '../package.json')).toString())
+const { version, name } = JSON.parse(fs.readFileSync(path.resolve(path.dirname((fileURLToPath(import.meta.url))), '../package.json')).toString())
 
 const execSync = (cmd) => {
   try {
@@ -34,4 +34,15 @@ const stripIndent = (string) => {
   return string.replace(regex, '')
 }
 
-export { execSync, stripIndent, version, name }
+function resolveInside(rootDir, ...segments) {
+  const nextPath = path.resolve(rootDir, ...segments)
+  const relative = path.relative(rootDir, nextPath)
+
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Path escapes root: ${nextPath}`)
+  }
+
+  return nextPath
+}
+
+export { execSync, stripIndent, resolveInside, version, name }