zeropress-theme 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# zeropress-theme
+
+ZeroPress 테마 개발/검증/패키징을 위한 developer toolkit입니다.
+
+## Install
+
+```bash
+# npx로 직접 실행 (설치 불필요)
+npx zeropress-theme <command>
+
+# 또는 글로벌 설치
+npm install -g zeropress-theme
+```
+
+## Commands
+
+### dev — 프리뷰 서버
+
+```bash
+npx zeropress-theme dev [themeDir] [options]
+```
+
+테마를 브라우저에서 실시간 프리뷰합니다. 파일 변경 시 WebSocket 기반 full reload를 지원합니다.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--port <number>` | 서버 포트 | `4321` |
+| `--host <ip>` | 바인드 주소 | `127.0.0.1` |
+| `--data <path-or-url>` | 프리뷰 데이터 JSON 경로 또는 HTTPS URL | 내장 샘플 데이터 |
+| `--open` | 브라우저 자동 열기 | - |
+| `--no-js-check` | JS 관련 점검 생략 | - |
+
+```bash
+# 현재 디렉토리 테마 프리뷰
+npx zeropress-theme dev
+
+# 경로 지정 + 커스텀 데이터
+npx zeropress-theme dev ./my-theme --data ./preview.json
+
+# 원격 데이터 사용
+npx zeropress-theme dev ./my-theme --data https://signed-url/preview.json
+```
+
+`--data` 미지정 시 toolkit 내장 샘플 데이터를 사용합니다. 원격 URL은 HTTPS만 허용하며, 최대 1MB, 타임아웃 5초입니다.
+
+---
+
+### validate — 테마 검증
+
+```bash
+npx zeropress-theme validate [themeDir] [options]
+```
+
+[Theme Spec Runtime v0.1](https://github.com/user/zeropress/blob/main/theme_guide_v2/THEME_SPEC.md) 계약 충족 여부를 확인합니다.
+
+| Option | Description |
+|--------|-------------|
+| `--strict` | 경고도 실패로 처리 |
+| `--json` | JSON 형식 출력 |
+
+#### 검증 항목
+
+**Error (업로드 차단)**
+- `theme.json` 누락/파싱 실패/필수 필드(`name`, `version`, `author`) 누락
+- `version` semver 불일치
+- 필수 템플릿 누락: `layout.html`, `index.html`, `post.html`, `page.html`
+- `assets/style.css` 누락
+- `layout.html`에 `{{slot:content}}` 정확히 1개가 아닌 경우
+- `layout.html`에 `<script>` 포함
+- 허용 슬롯(`content`, `header`, `footer`, `meta`) 외 사용
+- 중첩 슬롯, Mustache 블록 문법(`{{#...}}`, `{{/...}}`)
+- 경로 이탈(`../`, absolute path, symlink escape)
+
+**Warning**
+- `archive.html`, `category.html`, `tag.html` 누락
+
+#### 종료 코드
+
+| Code | Meaning |
+|------|---------|
+| `0` | 오류/경고 없음 |
+| `1` | 오류 존재 |
+| `2` | 경고만 존재 |
+
+`--strict` 사용 시 경고가 있으면 exit code `1`로 처리됩니다.
+
+#### --json 출력 예시
+
+```json
+{
+  "ok": false,
+  "summary": { "errors": 1, "warnings": 2, "checkedFiles": 14 },
+  "errors": [
+    { "code": "MISSING_REQUIRED_TEMPLATE", "path": "layout.html", "message": "Required template 'layout.html' is missing" }
+  ],
+  "warnings": [
+    { "code": "MISSING_OPTIONAL_TEMPLATE", "path": "archive.html", "message": "Optional template 'archive.html' is missing" }
+  ],
+  "meta": {
+    "schemaVersion": "1",
+    "tool": "zeropress-theme",
+    "toolVersion": "0.1.0",
+    "timestamp": "2026-02-14T00:00:00.000Z"
+  }
+}
+```
+
+---
+
+### pack — zip 패키징
+
+```bash
+npx zeropress-theme pack [themeDir] [options]
+```
+
+테마를 업로드용 zip으로 패키징합니다.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--out <dir>` | 출력 디렉토리 | `dist` |
+| `--name <file>` | zip 파일명 | `{name}-{version}.zip` |
+
+```bash
+npx zeropress-theme pack
+npx zeropress-theme pack ./my-theme --out artifacts
+npx zeropress-theme pack ./my-theme --name my-theme-v1.zip
+```
+
+동작 순서:
+1. `validate` 선실행 (실패 시 중단)
+2. 불필요 파일 제외 후 zip 생성 (루트 평탄화)
+3. 생성된 zip을 다시 읽어 validate 재실행 (재검증 실패 시 zip 삭제)
+
+자동 제외 파일: `.git`, `node_modules`, `dist`, `*.log`, `__MACOSX`, `.DS_Store`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`
+
+## CI 사용 예시
+
+```bash
+npx zeropress-theme validate ./theme --strict
+npx zeropress-theme pack ./theme --out ./artifacts
+```
+
+## Preview Data
+
+`dev` 명령에서 사용하는 프리뷰 데이터 JSON의 최소 구조:
+
+```json
+{
+  "site": {
+    "title": "My Site",
+    "description": "Preview description",
+    "url": "https://example.com",
+    "language": "ko"
+  },
+  "posts": [],
+  "pages": [],
+  "categories": [],
+  "tags": []
+}
+```
+
+필수: `site.title`, `site.description`, `site.url`, `site.language`
+`posts`, `pages`, `categories`, `tags`는 생략 가능(빈 배열 처리).
+
+공식 스키마: [preview-data.schema.json](https://github.com/user/zeropress/blob/main/theme_guide_v2/preview-data.schema.json)
+
+## Requirements
+
+- Node.js >= 18.18.0
+- ESM only
+
+## Related
+
+- [create-zeropress-theme](https://www.npmjs.com/package/create-zeropress-theme) — 테마 scaffolding CLI
+- [ZeroPress Theme Spec](https://github.com/user/zeropress/blob/main/theme_guide_v2/THEME_SPEC.md)
+
+## License
+
+MIT

package/bin/zeropress-theme.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(`[zeropress-theme] ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "zeropress-theme",
+  "version": "0.1.0",
+  "description": "ZeroPress theme developer toolkit",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "zeropress-theme": "./bin/zeropress-theme.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "dependencies": {
+    "jszip": "^3.10.1",
+    "ws": "^8.18.0"
+  }
+}

package/src/constants.js

@@ -0,0 +1,20 @@
+export const REQUIRED_TEMPLATES = ['layout.html', 'index.html', 'post.html', 'page.html'];
+export const OPTIONAL_TEMPLATES = ['archive.html', 'category.html', 'tag.html'];
+export const REQUIRED_FILES = ['theme.json', 'assets/style.css'];
+
+export const ALLOWED_SLOTS = new Set(['content', 'header', 'footer', 'meta']);
+
+export const EXCLUDE_DEFAULTS = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  '__MACOSX',
+  '.DS_Store',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lockb',
+]);
+
+export const MAX_REMOTE_DATA_BYTES = 1024 * 1024;
+export const REMOTE_TIMEOUT_MS = 5000;

package/src/dev.js

@@ -0,0 +1,406 @@
+import fs from 'node:fs/promises';
+import { watch as watchFs } from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { WebSocketServer } from 'ws';
+import { MAX_REMOTE_DATA_BYTES, REMOTE_TIMEOUT_MS } from './constants.js';
+import { getThemeDir, isHttpUrl, isHttpsUrl } from './helpers.js';
+import { validateThemeDirectory } from './validate.js';
+
+export async function runDev(argv) {
+  const { positional, flags } = parseDevArgs(argv);
+  const themeDir = getThemeDir(positional[0]);
+  const host = flags.host || '127.0.0.1';
+  const port = Number(flags.port || 4321);
+  const noJsCheck = flags['no-js-check'] === true;
+
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error(`Invalid port: ${flags.port}`);
+  }
+
+  const validation = await validateThemeDirectory(themeDir, { noJsCheck });
+  if (validation.errors.length > 0) {
+    throw new Error(`Theme validation failed before dev start (${validation.errors.length} errors)`);
+  }
+  if (validation.warnings.length > 0) {
+    console.log(`[dev] warnings: ${validation.warnings.length}`);
+  }
+
+  const previewData = await loadPreviewData(flags.data);
+  ensurePreviewDataMinimum(previewData);
+
+  const server = http.createServer((req, res) => handleRequest(req, res, themeDir, previewData));
+  const wss = new WebSocketServer({ server, path: '/__zeropress_ws' });
+
+  const watchers = await createWatchers(themeDir, async () => {
+    if (!noJsCheck) {
+      const quick = await validateThemeDirectory(themeDir, { noJsCheck: false });
+      if (quick.errors.length > 0) {
+        console.log(`[dev] validation errors on change: ${quick.errors.length}`);
+      }
+    }
+
+    for (const client of wss.clients) {
+      if (client.readyState === 1) {
+        client.send('reload');
+      }
+    }
+  });
+
+  server.listen(port, host, () => {
+    const url = `http://${host}:${port}`;
+    console.log(`[dev] running at ${url}`);
+    if (flags.open === true) {
+      openBrowser(url);
+    }
+  });
+
+  const shutdown = () => {
+    for (const watcher of watchers) {
+      watcher.close();
+    }
+    wss.close();
+    server.close(() => process.exit(0));
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+function parseDevArgs(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    const key = token.slice(2);
+    if (key === 'open' || key === 'no-js-check') {
+      flags[key] = true;
+      continue;
+    }
+
+    if (key === 'port' || key === 'host' || key === 'data') {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error(`--${key} requires a value`);
+      }
+      flags[key] = value;
+      i += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown option for dev: ${token}`);
+  }
+
+  return { positional, flags };
+}
+
+async function loadPreviewData(dataArg) {
+  if (!dataArg) {
+    return defaultPreviewData();
+  }
+
+  if (isHttpUrl(dataArg)) {
+    if (!isHttpsUrl(dataArg)) {
+      throw new Error('--data URL must use https');
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REMOTE_TIMEOUT_MS);
+
+    try {
+      const response = await fetch(dataArg, { redirect: 'follow', signal: controller.signal });
+      if (!response.ok) {
+        throw new Error(`Failed to fetch preview data (${response.status})`);
+      }
+      const raw = new Uint8Array(await response.arrayBuffer());
+      if (raw.byteLength > MAX_REMOTE_DATA_BYTES) {
+        throw new Error('Remote preview JSON exceeds 1MB limit');
+      }
+      return JSON.parse(new TextDecoder().decode(raw));
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  const localPath = path.resolve(process.cwd(), dataArg);
+  const raw = await fs.readFile(localPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function ensurePreviewDataMinimum(data) {
+  if (!data || typeof data !== 'object') {
+    throw new Error('Preview data must be an object');
+  }
+  if (!data.site || typeof data.site !== 'object') {
+    throw new Error('Preview data must include site object');
+  }
+  for (const key of ['title', 'description', 'url', 'language']) {
+    if (typeof data.site[key] !== 'string' || data.site[key].trim() === '') {
+      throw new Error(`Preview data site.${key} is required`);
+    }
+  }
+}
+
+function defaultPreviewData() {
+  return {
+    site: {
+      title: 'ZeroPress Preview',
+      description: 'Default preview data',
+      url: 'https://example.com',
+      language: 'en',
+    },
+    posts: [
+      {
+        title: 'Hello ZeroPress',
+        slug: 'hello-zeropress',
+        html: '<p>Preview post content</p>',
+        excerpt: 'Preview excerpt',
+        published_at: '2026-02-14',
+        updated_at: '2026-02-14',
+        author_name: 'Admin',
+      },
+    ],
+    pages: [
+      {
+        title: 'About',
+        slug: 'about',
+        html: '<p>About page</p>',
+      },
+    ],
+    categories: [{ name: 'General', slug: 'general', postCount: 1 }],
+    tags: [{ name: 'Intro', slug: 'intro', postCount: 1 }],
+  };
+}
+
+async function handleRequest(req, res, themeDir, data) {
+  try {
+    const url = new URL(req.url, 'http://localhost');
+    const pathname = decodeURIComponent(url.pathname);
+
+    if (pathname.startsWith('/assets/')) {
+      const assetPath = path.join(themeDir, pathname);
+      const content = await fs.readFile(assetPath);
+      const type = pathname.endsWith('.css') ? 'text/css; charset=utf-8' : 'application/octet-stream';
+      send(res, 200, type, content);
+      return;
+    }
+
+    const rendered = await renderRoute(pathname, themeDir, data);
+    if (rendered.notFound) {
+      send(res, 404, 'text/html; charset=utf-8', injectLiveReload(rendered.html));
+      return;
+    }
+
+    send(res, 200, 'text/html; charset=utf-8', injectLiveReload(rendered.html));
+  } catch (error) {
+    send(res, 500, 'text/plain; charset=utf-8', `Internal error: ${error.message}`);
+  }
+}
+
+async function renderRoute(pathname, themeDir, data) {
+  const normalized = pathname.replace(/\/+$/, '') || '/';
+
+  if (normalized === '/') {
+    return { html: await renderWithLayout(themeDir, 'index.html', { ...data, posts: renderPostList(data.posts) }) };
+  }
+
+  const postMatch = normalized.match(/^\/posts\/([^/]+)$/);
+  if (postMatch) {
+    const post = (data.posts || []).find((p) => p.slug === postMatch[1]);
+    if (!post) {
+      return { html: await render404(themeDir), notFound: true };
+    }
+    return { html: await renderWithLayout(themeDir, 'post.html', { ...data, post }) };
+  }
+
+  const pageMatch = normalized.match(/^\/([^/]+)$/);
+  if (pageMatch && pageMatch[1] !== 'archive') {
+    const page = (data.pages || []).find((p) => p.slug === pageMatch[1]);
+    if (!page) {
+      return { html: await render404(themeDir), notFound: true };
+    }
+    return { html: await renderWithLayout(themeDir, 'page.html', { ...data, page }) };
+  }
+
+  if (normalized === '/archive') {
+    if (!(await fileExists(path.join(themeDir, 'archive.html')))) {
+      return { html: await render404(themeDir), notFound: true };
+    }
+    return { html: await renderWithLayout(themeDir, 'archive.html', { ...data, posts: renderPostList(data.posts) }) };
+  }
+
+  const categoryMatch = normalized.match(/^\/categories\/([^/]+)$/);
+  if (categoryMatch) {
+    if (!(await fileExists(path.join(themeDir, 'category.html')))) {
+      return { html: await render404(themeDir), notFound: true };
+    }
+    const posts = (data.posts || []).filter((post) => {
+      const list = post.categories || [];
+      return list.includes(categoryMatch[1]) || list.includes(capitalize(categoryMatch[1]));
+    });
+    return { html: await renderWithLayout(themeDir, 'category.html', { ...data, posts: renderPostList(posts) }) };
+  }
+
+  const tagMatch = normalized.match(/^\/tags\/([^/]+)$/);
+  if (tagMatch) {
+    if (!(await fileExists(path.join(themeDir, 'tag.html')))) {
+      return { html: await render404(themeDir), notFound: true };
+    }
+    const posts = (data.posts || []).filter((post) => {
+      const list = post.tags || [];
+      return list.includes(tagMatch[1]) || list.includes(capitalize(tagMatch[1]));
+    });
+    return { html: await renderWithLayout(themeDir, 'tag.html', { ...data, posts: renderPostList(posts) }) };
+  }
+
+  return { html: await render404(themeDir), notFound: true };
+}
+
+function renderPostList(posts = []) {
+  if (!posts.length) {
+    return '<p>No posts</p>';
+  }
+  return posts
+    .map((post) => `<article><h2><a href="/posts/${post.slug}">${escapeHtml(post.title || '')}</a></h2><div>${post.excerpt || ''}</div></article>`)
+    .join('\n');
+}
+
+async function renderWithLayout(themeDir, templateName, data) {
+  const [layout, template] = await Promise.all([
+    fs.readFile(path.join(themeDir, 'layout.html'), 'utf8'),
+    fs.readFile(path.join(themeDir, templateName), 'utf8'),
+  ]);
+
+  const header = await readOptional(path.join(themeDir, 'partials', 'header.html'));
+  const footer = await readOptional(path.join(themeDir, 'partials', 'footer.html'));
+  const body = substitute(template, data);
+
+  const withSlots = layout
+    .replace(/\{\{slot:content\}\}/g, body)
+    .replace(/\{\{slot:header\}\}/g, header)
+    .replace(/\{\{slot:footer\}\}/g, footer)
+    .replace(/\{\{slot:meta\}\}/g, '');
+
+  return substitute(withSlots, data);
+}
+
+async function render404(themeDir) {
+  const custom404 = path.join(themeDir, '404.html');
+  if (await fileExists(custom404)) {
+    return renderWithLayout(themeDir, '404.html', {
+      site: {
+        title: '404',
+        description: 'Not found',
+      },
+    });
+  }
+  return '<!doctype html><html><body><h1>404</h1><p>Not Found</p></body></html>';
+}
+
+function substitute(template, data) {
+  return template.replace(/\{\{([a-zA-Z0-9_.-]+)\}\}/g, (_, key) => {
+    if (key.startsWith('slot:')) {
+      return `{{${key}}}`;
+    }
+    const value = getByPath(data, key);
+    return value == null ? '' : String(value);
+  });
+}
+
+function getByPath(obj, key) {
+  const parts = key.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+function injectLiveReload(html) {
+  const script = `\n<script>\n(() => {\n  const ws = new WebSocket((location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host + '/__zeropress_ws');\n  ws.onmessage = (event) => { if (event.data === 'reload') location.reload(); };\n})();\n</script>\n`;
+  if (html.includes('</body>')) {
+    return html.replace('</body>', `${script}</body>`);
+  }
+  return `${html}${script}`;
+}
+
+function send(res, status, type, body) {
+  res.writeHead(status, { 'content-type': type });
+  res.end(body);
+}
+
+function escapeHtml(value) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function capitalize(value) {
+  if (!value) return value;
+  return value[0].toUpperCase() + value.slice(1);
+}
+
+async function readOptional(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return '';
+    throw error;
+  }
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createWatchers(rootDir, onChange) {
+  const watchers = [];
+
+  async function watchDir(dir) {
+    const watcher = watchFs(dir, { persistent: true }, () => {
+      onChange().catch((error) => {
+        console.log(`[dev] reload trigger error: ${error.message}`);
+      });
+    });
+    watchers.push(watcher);
+
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await watchDir(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  await watchDir(rootDir);
+  return watchers;
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+  } else if (platform === 'win32') {
+    spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+  } else {
+    spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+  }
+}

package/src/helpers.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function parseCliArgs(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = token.split('=');
+    const key = rawKey.slice(2);
+
+    if (inlineValue !== undefined) {
+      flags[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      flags[key] = true;
+      continue;
+    }
+
+    flags[key] = next;
+    i += 1;
+  }
+
+  return { positional, flags };
+}
+
+export function toBoolean(value) {
+  return value === true || value === 'true' || value === '1';
+}
+
+export async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isHttpUrl(value) {
+  return typeof value === 'string' && /^https?:\/\//i.test(value);
+}
+
+export function isHttpsUrl(value) {
+  return typeof value === 'string' && /^https:\/\//i.test(value);
+}
+
+export function normalizeSlashes(value) {
+  return value.replace(/\\/g, '/');
+}
+
+export function sanitizeFileName(value) {
+  return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'theme';
+}
+
+export async function walkDirectory(rootDir) {
+  const output = [];
+
+  async function walk(currentDir) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      const relativePath = normalizeSlashes(path.relative(rootDir, fullPath));
+      output.push({
+        fullPath,
+        relativePath,
+        entry,
+      });
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      }
+    }
+  }
+
+  await walk(rootDir);
+  return output;
+}
+
+export function getThemeDir(inputDir) {
+  return path.resolve(process.cwd(), inputDir || '.');
+}

package/src/index.js

@@ -0,0 +1,39 @@
+import { runValidate } from './validate.js';
+import { runPack } from './pack.js';
+import { runDev } from './dev.js';
+
+export async function run(argv) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'validate') {
+    const code = await runValidate(rest);
+    process.exit(code);
+    return;
+  }
+
+  if (command === 'pack') {
+    await runPack(rest);
+    return;
+  }
+
+  if (command === 'dev') {
+    await runDev(rest);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+function printHelp() {
+  console.log(`zeropress-theme v0.1.0
+
+Usage:
+  zeropress-theme dev [themeDir] [--port <n>] [--host <ip>] [--data <path-or-url>] [--open] [--no-js-check]
+  zeropress-theme validate [themeDir] [--strict] [--json]
+  zeropress-theme pack [themeDir] [--out <dir>] [--name <zipFile>]`);
+}

package/src/pack.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import JSZip from 'jszip';
+import { EXCLUDE_DEFAULTS } from './constants.js';
+import { getThemeDir, normalizeSlashes, sanitizeFileName, walkDirectory } from './helpers.js';
+import { validateThemeDirectory, validateZipFile } from './validate.js';
+
+export async function runPack(argv) {
+  const { positional, flags } = parsePackArgs(argv);
+  const themeDir = getThemeDir(positional[0]);
+  const outDir = path.resolve(process.cwd(), flags.out || 'dist');
+
+  const preValidation = await validateThemeDirectory(themeDir, { noJsCheck: false });
+  if (preValidation.errors.length > 0) {
+    throw new Error(`Pack aborted: validate failed with ${preValidation.errors.length} error(s)`);
+  }
+
+  const themeJsonRaw = await fs.readFile(path.join(themeDir, 'theme.json'), 'utf8');
+  const themeJson = JSON.parse(themeJsonRaw);
+  const defaultName = `${sanitizeFileName(themeJson.name)}-${sanitizeFileName(themeJson.version)}.zip`;
+  const fileName = flags.name || defaultName;
+
+  await fs.mkdir(outDir, { recursive: true });
+  const zipPath = path.join(outDir, fileName);
+
+  const zip = new JSZip();
+  const entries = await walkDirectory(themeDir);
+
+  const seenPaths = new Map();
+
+  for (const item of entries) {
+    if (!item.entry.isFile()) {
+      continue;
+    }
+
+    const rel = normalizeSlashes(item.relativePath);
+    if (shouldExclude(rel)) {
+      continue;
+    }
+
+    const zipRel = rel;
+    const key = zipRel.toLowerCase();
+    if (seenPaths.has(key)) {
+      throw new Error(`Pack aborted: flatten path collision detected (${zipRel} conflicts with ${seenPaths.get(key)})`);
+    }
+    seenPaths.set(key, zipRel);
+
+    const content = await fs.readFile(item.fullPath);
+    zip.file(zipRel, content);
+  }
+
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  await fs.writeFile(zipPath, buffer);
+
+  const postValidation = await validateZipFile(zipPath, { noJsCheck: false });
+  if (postValidation.errors.length > 0) {
+    await fs.unlink(zipPath).catch(() => {});
+    throw new Error(`Pack aborted: generated zip re-validation failed with ${postValidation.errors.length} error(s)`);
+  }
+
+  console.log(`Packed theme: ${zipPath}`);
+  if (postValidation.warnings.length > 0) {
+    console.log(`Pack warnings: ${postValidation.warnings.length}`);
+  }
+}
+
+function parsePackArgs(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    if (token === '--out' || token === '--name') {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error(`${token} requires a value`);
+      }
+      flags[token.slice(2)] = value;
+      i += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown option for pack: ${token}`);
+  }
+
+  return { positional, flags };
+}
+
+function shouldExclude(relativePath) {
+  const parts = relativePath.split('/');
+  for (const part of parts) {
+    if (EXCLUDE_DEFAULTS.has(part)) {
+      return true;
+    }
+  }
+  if (relativePath.endsWith('.log')) {
+    return true;
+  }
+  return false;
+}

package/src/validate.js

@@ -0,0 +1,342 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import JSZip from 'jszip';
+import { ALLOWED_SLOTS, OPTIONAL_TEMPLATES, REQUIRED_FILES, REQUIRED_TEMPLATES } from './constants.js';
+import { getThemeDir, normalizeSlashes, walkDirectory } from './helpers.js';
+
+export async function runValidate(argv) {
+  const { positional, flags } = parseValidateArgs(argv);
+  const themeDir = getThemeDir(positional[0]);
+  const strict = flags.strict === true;
+  const json = flags.json === true;
+
+  const result = await validateThemeDirectory(themeDir, { noJsCheck: false });
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(toJsonOutput(result), null, 2)}\n`);
+  } else {
+    printHuman(result, themeDir);
+  }
+
+  if (result.errors.length > 0) {
+    return 1;
+  }
+  if (result.warnings.length > 0) {
+    return strict ? 1 : 2;
+  }
+  return 0;
+}
+
+function parseValidateArgs(argv) {
+  const positional = [];
+  const flags = { strict: false, json: false };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+    if (token === '--strict') {
+      flags.strict = true;
+      continue;
+    }
+    if (token === '--json') {
+      flags.json = true;
+      continue;
+    }
+    throw new Error(`Unknown option for validate: ${token}`);
+  }
+
+  return { positional, flags };
+}
+
+export async function validateThemeDirectory(themeDir, options = {}) {
+  const noJsCheck = options.noJsCheck === true;
+  const errors = [];
+  const warnings = [];
+  let checkedFiles = 0;
+
+  const allEntries = await walkDirectory(themeDir);
+  checkedFiles = allEntries.filter((it) => it.entry.isFile()).length;
+
+  await validatePathSafety(themeDir, allEntries, errors);
+
+  const files = new Map();
+  for (const item of allEntries) {
+    if (item.entry.isFile()) {
+      files.set(item.relativePath, item.fullPath);
+    }
+  }
+
+  await validateFromFileMap(files, {
+    readFile: (relativePath) => fs.readFile(files.get(relativePath), 'utf8'),
+    exists: (relativePath) => files.has(relativePath),
+    errors,
+    warnings,
+    noJsCheck,
+  });
+
+  return { ok: errors.length === 0, errors, warnings, checkedFiles };
+}
+
+export async function validateZipFile(zipPath, options = {}) {
+  const noJsCheck = options.noJsCheck === true;
+  const errors = [];
+  const warnings = [];
+
+  const raw = await fs.readFile(zipPath);
+  const zip = await JSZip.loadAsync(raw);
+
+  const filePaths = Object.keys(zip.files).filter((p) => !zip.files[p].dir);
+  const basePrefix = detectBasePrefix(filePaths);
+
+  const files = new Set(filePaths.map((p) => normalizeSlashes(p)));
+
+  await validateFromFileMap(
+    new Proxy(
+      {},
+      {
+        get: (_, key) => files.has(`${basePrefix}${key}`),
+      }
+    ),
+    {
+      readFile: async (relativePath) => {
+        const file = zip.file(`${basePrefix}${relativePath}`);
+        if (!file) {
+          throw new Error(`Missing file: ${relativePath}`);
+        }
+        return file.async('string');
+      },
+      exists: (relativePath) => files.has(`${basePrefix}${relativePath}`),
+      errors,
+      warnings,
+      noJsCheck,
+    }
+  );
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    checkedFiles: filePaths.length,
+  };
+}
+
+function detectBasePrefix(filePaths) {
+  if (filePaths.includes('theme.json')) {
+    return '';
+  }
+  const topLevel = new Set(filePaths.map((p) => p.split('/')[0]).filter(Boolean));
+  if (topLevel.size === 1) {
+    const folder = Array.from(topLevel)[0];
+    if (filePaths.includes(`${folder}/theme.json`)) {
+      return `${folder}/`;
+    }
+  }
+  return '';
+}
+
+async function validateFromFileMap(fileMap, context) {
+  const { exists, readFile, errors, warnings, noJsCheck } = context;
+
+  for (const requiredPath of REQUIRED_FILES) {
+    if (!exists(requiredPath)) {
+      errors.push({
+        code: 'MISSING_REQUIRED_FILE',
+        path: requiredPath,
+        message: `Required file '${requiredPath}' is missing`,
+      });
+    }
+  }
+
+  for (const template of REQUIRED_TEMPLATES) {
+    if (!exists(template)) {
+      errors.push({
+        code: 'MISSING_REQUIRED_TEMPLATE',
+        path: template,
+        message: `Required template '${template}' is missing`,
+      });
+    }
+  }
+
+  for (const template of OPTIONAL_TEMPLATES) {
+    if (!exists(template)) {
+      warnings.push({
+        code: 'MISSING_OPTIONAL_TEMPLATE',
+        path: template,
+        message: `Optional template '${template}' is missing`,
+      });
+    }
+  }
+
+  if (exists('theme.json')) {
+    try {
+      const raw = await readFile('theme.json');
+      const data = JSON.parse(raw);
+      validateThemeJson(data, errors);
+    } catch (error) {
+      errors.push({
+        code: 'INVALID_THEME_JSON',
+        path: 'theme.json',
+        message: `Invalid theme.json: ${error.message}`,
+      });
+    }
+  }
+
+  const templatesToCheck = [...REQUIRED_TEMPLATES, ...OPTIONAL_TEMPLATES, 'layout.html', '404.html'];
+  for (const template of new Set(templatesToCheck)) {
+    if (!exists(template)) {
+      continue;
+    }
+    const content = await readFile(template);
+    validateTemplateSyntax(template, content, errors, noJsCheck);
+  }
+
+  if (exists('partials')) {
+    // no-op for virtual sources
+  }
+}
+
+function validateThemeJson(themeJson, errors) {
+  if (!themeJson || typeof themeJson !== 'object') {
+    errors.push({
+      code: 'INVALID_THEME_JSON',
+      path: 'theme.json',
+      message: 'theme.json must be an object',
+    });
+    return;
+  }
+
+  for (const key of ['name', 'version', 'author']) {
+    if (typeof themeJson[key] !== 'string' || themeJson[key].trim() === '') {
+      errors.push({
+        code: 'INVALID_THEME_METADATA',
+        path: 'theme.json',
+        message: `theme.json field '${key}' must be a non-empty string`,
+      });
+    }
+  }
+
+  if (typeof themeJson.version === 'string') {
+    const semver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+    if (!semver.test(themeJson.version)) {
+      errors.push({
+        code: 'INVALID_SEMVER',
+        path: 'theme.json',
+        message: "Theme version must follow semantic versioning (e.g. 1.0.0)",
+      });
+    }
+  }
+}
+
+function validateTemplateSyntax(templatePath, content, errors, noJsCheck) {
+  const slotRegex = /\{\{slot:([a-zA-Z0-9_-]+)\}\}/g;
+  const contentSlotMatches = content.match(/\{\{slot:content\}\}/g) || [];
+
+  if (templatePath === 'layout.html') {
+    if (contentSlotMatches.length !== 1) {
+      errors.push({
+        code: 'INVALID_LAYOUT_SLOT',
+        path: 'layout.html',
+        message: 'layout.html must contain exactly one {{slot:content}}',
+      });
+    }
+    if (!noJsCheck && /<script\b/i.test(content)) {
+      errors.push({
+        code: 'LAYOUT_SCRIPT_NOT_ALLOWED',
+        path: 'layout.html',
+        message: 'layout.html must not contain <script> tags',
+      });
+    }
+  }
+
+  let match;
+  while ((match = slotRegex.exec(content)) !== null) {
+    const slotName = match[1];
+    if (!ALLOWED_SLOTS.has(slotName)) {
+      errors.push({
+        code: 'UNKNOWN_SLOT',
+        path: templatePath,
+        message: `Unknown slot '${slotName}' in ${templatePath}`,
+      });
+    }
+  }
+
+  if (/\{\{slot:[^}]*\{\{slot:/.test(content)) {
+    errors.push({
+      code: 'NESTED_SLOT',
+      path: templatePath,
+      message: `Nested slots are not allowed in ${templatePath}`,
+    });
+  }
+
+  if (/\{\{[#/][^}]+\}\}/.test(content)) {
+    errors.push({
+      code: 'MUSTACHE_BLOCK_NOT_ALLOWED',
+      path: templatePath,
+      message: `Mustache block syntax is not allowed in ${templatePath}`,
+    });
+  }
+}
+
+async function validatePathSafety(themeDir, entries, errors) {
+  const rootRealPath = await fs.realpath(themeDir);
+  for (const item of entries) {
+    const rel = item.relativePath;
+    if (rel.includes('..') || path.isAbsolute(rel)) {
+      errors.push({
+        code: 'PATH_ESCAPE',
+        path: rel,
+        message: `Invalid path outside theme root: ${rel}`,
+      });
+      continue;
+    }
+
+    const full = item.fullPath;
+    const stat = await fs.lstat(full);
+    if (!stat.isSymbolicLink()) {
+      continue;
+    }
+    const resolved = await fs.realpath(full);
+    if (!resolved.startsWith(rootRealPath)) {
+      errors.push({
+        code: 'SYMLINK_ESCAPE',
+        path: rel,
+        message: `Symlink escapes theme root: ${rel}`,
+      });
+    }
+  }
+}
+
+function printHuman(result, themeDir) {
+  console.log(`Validating theme: ${themeDir}`);
+  for (const error of result.errors) {
+    console.log(`ERROR ${error.code} ${error.path}: ${error.message}`);
+  }
+  for (const warning of result.warnings) {
+    console.log(`WARN  ${warning.code} ${warning.path}: ${warning.message}`);
+  }
+  if (result.errors.length === 0 && result.warnings.length === 0) {
+    console.log('OK Theme is valid');
+  }
+}
+
+function toJsonOutput(result) {
+  return {
+    ok: result.errors.length === 0,
+    summary: {
+      errors: result.errors.length,
+      warnings: result.warnings.length,
+      checkedFiles: result.checkedFiles,
+    },
+    errors: result.errors,
+    warnings: result.warnings,
+    meta: {
+      schemaVersion: '1',
+      tool: 'zeropress-theme',
+      toolVersion: '0.1.0',
+      timestamp: new Date().toISOString(),
+    },
+  };
+}