@newlogic-digital/cli 1.4.1 → 1.5.0-next.2

package/index.mjs

@@ -2,13 +2,76 @@
 
 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'
 
+const knownCommands = ['init', 'cms', 'blocks']
+
 function normalizeOptionName(name) {
   return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
 }
 
+function getLevenshteinDistance(left, right) {
+  const distances = Array.from({ length: left.length + 1 }, () => Array(right.length + 1).fill(0))
+
+  for (let row = 0; row <= left.length; row++) {
+    distances[row][0] = row
+  }
+
+  for (let column = 0; column <= right.length; column++) {
+    distances[0][column] = column
+  }
+
+  for (let row = 1; row <= left.length; row++) {
+    for (let column = 1; column <= right.length; column++) {
+      const substitutionCost = left[row - 1] === right[column - 1] ? 0 : 1
+
+      distances[row][column] = Math.min(
+        distances[row - 1][column] + 1,
+        distances[row][column - 1] + 1,
+        distances[row - 1][column - 1] + substitutionCost,
+      )
+    }
+  }
+
+  return distances[left.length][right.length]
+}
+
+function getSuggestedCommand(command) {
+  const normalizedCommand = `${command ?? ''}`.trim().toLowerCase()
+
+  if (!normalizedCommand) {
+    return undefined
+  }
+
+  const suggestion = knownCommands
+    .map(candidate => ({ candidate, distance: getLevenshteinDistance(normalizedCommand, candidate) }))
+    .sort((left, right) => left.distance - right.distance)[0]
+
+  if (suggestion && suggestion.distance <= 2) {
+    return suggestion.candidate
+  }
+
+  return undefined
+}
+
+function printUnknownCommand(command) {
+  const suggestion = getSuggestedCommand(command)
+  const lines = [
+    `${styleText(['red', 'bold'], 'error')} Unknown command ${styleText(['yellow', 'bold'], `"${command}"`)}`,
+  ]
+
+  if (suggestion) {
+    lines.push(`${styleText(['cyan', 'bold'], 'hint')} Did you mean ${styleText(['green', 'bold'], `"${suggestion}"`)}?`)
+  }
+
+  lines.push(`${styleText(['white', 'bold'], 'available')} ${knownCommands.map(command => styleText('green', command)).join(', ')}`)
+  lines.push(`${styleText(['cyan', 'bold'], 'help')} Run ${styleText('green', 'newlogic')} to see full usage`)
+
+  console.log(lines.join('\n'))
+}
+
 function parseCommandArgs(args) {
   const positionals = []
   const options = {}
@@ -60,30 +123,44 @@ 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')}
+  `)
+
+  process.exit(0)
 }
 
 if (command === 'init') {
@@ -101,3 +178,16 @@ 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)
+}
+
+if (command && !knownCommands.includes(command)) {
+  printUnknownCommand(command)
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newlogic-digital/cli",
-  "version": "1.4.1",
+  "version": "1.5.0-next.2",
   "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/templates/components/article/ArticleGridHorizontal.latte

@@ -0,0 +1,28 @@
+<section class="x-article-grid-horizontal grid grid-cols-container gap-y-12 md:gap-y-16 py-20 md:py-24 lg:py-28">
+    <div class="flex items-end gap-x-10 gap-y-6 w-full justify-between max-md:flex-col">
+        <div class="flex flex-col w-full lg:flex-1/2 items-start max-w-161">
+            <div class="x-badge mb-1 accent-main-secondary muted">
+                Section title
+            </div>
+            <h2 class="x-heading lg:lg  mb-6">
+                Attention-grabbing medium length section headline
+            </h2>
+            <div class="x-text w-full">
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+                Suspendisse varius enim in eros elementum tristique.
+                Duis cursus, mi quis viverra ornare, eros dolor interdum nulla.
+            </div>
+        </div>
+        <a href="#" class="x-button lg max-md:mr-auto">
+            View all
+            <svg class="me-auto size-5" aria-hidden="true">
+                <use href="#heroicons-mini/arrow-right"/>
+            </svg>
+        </a>
+    </div>
+    <div class="w-full grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+        {foreach range(1,$control->itemsCount ?? 6) as $i}
+            {include './ArticleItem.latte', itemVariant => $control->itemVariant, showAuthor => $control->showAuthor, lastHidden => true, mutedBadge => $control->itemVariant !== 'filled'}
+        {/foreach}
+    </div>
+</section>

package/src/templates/components/article/ArticleItem.latte

@@ -0,0 +1,59 @@
+{default $lastHidden = false}
+{default $itemVariant = 'basic'}
+{default $mutedBadge = false}
+{default $showAuthor = false}
+
+<a
+    n:class="'x-article-item group flex flex-col', $lastHidden ? 'max-md:last:hidden lg:last:hidden'"
+    href="/article/detail.html"
+>
+    <picture
+        n:class="
+            'x-image w-full before:skeleton aspect-310/207 md:aspect-310/207 lg:aspect-418/279 overflow-hidden',
+            $itemVariant === 'basic' ? 'rounded-2xl',
+            $itemVariant === 'outlined' ? 'rounded-t-2xl border-x border-t border-body-secondary',
+            $itemVariant === 'filled' ? 'rounded-t-2xl',
+        "
+    >
+        <source srcset="{=placeholder(345,431)}" media="(width < {$media->sm})">
+        <img
+            class="size-full object-cover group-hocus:scale-105 transition-transform"
+            src="{=placeholder(532,655)}"
+            alt=" " width="532" height="655" loading="lazy"
+        >
+    </picture>
+    <div
+        n:class="
+            'flex flex-col items-start pt-6 grow',
+            $itemVariant === 'outlined' ? 'rounded-b-2xl border-x border-b border-body-secondary px-6 pb-4',
+            $itemVariant === 'filled' ? 'bg-primary/5 px-6 pb-4 rounded-b-2xl',
+        "
+    >
+        <div class="flex gap-2 flex-wrap mb-3">
+            <div n:class="'x-badge sm', $mutedBadge ? 'muted' : ''">Article category</div>
+            <div class="x-badge sm  muted bg-transparent" n:if="!$showAuthor">5 min read</div>
+        </div>
+        <div class="x-heading xs mb-4 tracking-[-0.5px]">
+            Article title goes here
+        </div>
+        <div class="x-text text-main-secondary line-clamp-3 mb-4">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat.
+        </div>
+        <div class="grid grid-cols-[auto_1fr] mb-4 gap-x-4" n:if="$showAuthor">
+            <picture class="x-image before:skeleton size-12 rounded-full aspect-square shrink-0 row-span-2 overflow-hidden">
+                <img class="object-cover" src="{=placeholder(48,48)}" alt=" " width="48" height="48" loading="lazy">
+            </picture>
+            <span class="x-text sm font-medium self-end">Author Name</span>
+            <div class="flex gap-4">
+                <span class="x-text xs text-main-tertiary font-medium">04.12.2025</span>
+                <span class="x-text xs text-main-tertiary font-medium">5 min read</span>
+            </div>
+        </div>
+        <span class="x-button ghosted pl-1 mt-auto">
+            Read more
+            <svg class="me-auto size-5 group-hocus:translate-x-1 transition-transform" aria-hidden="true">
+                <use href="#heroicons-mini/arrow-right"/>
+            </svg>
+        </span>
+    </div>
+</a>

package/src/templates/components/header/HeaderNavLeft.latte

@@ -0,0 +1,71 @@
+<header class="x-header-nav-right h-(--x-header-height) grid grid-cols-container bg-body-primary sticky top-0 z-40">
+    <div class="flex items-center gap-1.5 md:gap-3">
+        <a href="#" class="shrink-0 max-lg:mr-auto lg:mr-7">
+            <img class="w-25 h-8" src="{placeholder(100,32)}" loading="lazy" alt="Logo">
+        </a>
+        <nav class="flex items-center flex-wrap justify-start gap-x-1 max-lg:hidden mr-auto">
+            <div class="x-popover trigger-hover group" n:foreach="range(1,4) as $item">
+                <a href="#" class="x-text x-link sm font-medium py-1 px-3 flex items-center gap-1.5">
+                    Menu item {$iterator->counter}
+                    <svg class="size-4 transition group-hocus:-scale-y-100" n:if="$iterator->last">
+                        <use href="#heroicons-solid/chevron-down" />
+                    </svg>
+                </a>
+                <div
+                    n:class="
+                        'x-nav-popover x-popover-content bottom-end border border-body-secondary shadow-lg min-w-55',
+                        'm-1.5 p-4 flex flex-col gap-1 before:-top-2.5 before:h-2.5'
+                    "
+                    n:if="$iterator->last"
+                >
+                    <a href="#" class="x-text x-link sm font-medium py-1 flex items-center gap-1.5" n:foreach="range(1,4) as $item">
+                        Menu item
+                    </a>
+                </div>
+            </div>
+        </nav>
+        <div class="x-popover trigger-focus group">
+            <button class="x-text x-link sm font-medium py-1 px-3 flex items-center gap-1.5" type="button" tabindex="0">
+                <img
+                    class="aspect-4/3 size-4"
+                    src="https://cdn.jsdelivr.net/npm/flag-icons@7.5.0/flags/1x1/gb.svg"
+                    alt="at"
+                    loading="lazy"
+                >
+                EN
+                <svg class="size-4 transition group-focus-within:-scale-y-100">
+                    <use href="#heroicons-solid/chevron-down" />
+                </svg>
+            </button>
+            <div class="x-popover-content bottom-end border border-body-secondary shadow-lg m-1.5 p-4 flex flex-col gap-1">
+                <a href="#" class="x-text x-link sm font-medium py-1 flex items-center gap-1.5" n:foreach="range(1,4) as $item">
+                    <img
+                        class="aspect-4/3 size-4"
+                        src="https://cdn.jsdelivr.net/npm/flag-icons@7.5.0/flags/1x1/gb.svg"
+                        alt="at"
+                        loading="lazy"
+                    >
+                    English
+                </a>
+            </div>
+        </div>
+        <a href="#" class="x-button sm max-md:hidden">
+            Call to action
+        </a>
+        <button
+            class="x-button square sm lg:hidden group swap"
+            type="button"
+            data-invoke-action="x-drawer#toggle"
+            data-invoke-target="#navDrawer"
+            aria-controls="navDrawer"
+            aria-expanded="false"
+        >
+            <svg class="size-5 shrink-0 not-group-aria-expanded:opacity-100 group-aria-expanded:rotate-45" aria-hidden="true">
+                <use href="#heroicons-solid/bars-3"></use>
+            </svg>
+            <svg class="size-5 shrink-0 not-group-aria-expanded:-rotate-45 group-aria-expanded:opacity-100" aria-hidden="true">
+                <use href="#heroicons-solid/x-mark"></use>
+            </svg>
+        </button>
+    </div>
+</header>

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 }