@easysociable/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,7 +1,6 @@
 # EasySociable CLI
 
-Agent-first CLI and MCP host for EasySociable Template and Slideshow V1.
-Gateway-only: no Local API, SQLite, or local renderer.
+Agent-first CLI for EasySociable: local Content Engine, Template, Slideshow, and MCP.
 
 ```bash
 npm i -g @easysociable/cli
@@ -9,25 +8,41 @@ npm i -g @easysociable/cli
 curl -fsSL https://easysociable.com/install.sh | bash
 ```
 
-Requires Node.js 20+.
+Requires Node.js 20+. Content Engine workbench also needs `python3`.
 
 ## Quick start
 
 ```bash
+# Visual skills + MCP for Codex / Claude Code
 easysociable install --yes
-# Tell your Agent what to make.
-# Sign up and run auth login only when Gateway asks for it.
+
+# Local content engine (markdown + workbench) — no Agent host required
+easysociable engine init --root /workspace --yes
+easysociable engine serve --engine /workspace/Content Engine --no-open
 ```
 
-Default `install` copies **Template + Slideshow** Skills and registers the
-unified MCP for Codex / Claude Code. Opt into the Obsidian Content Skill later:
+Then tell the Agent to follow `Content Engine/CLAUDE.md`.
+
+Optional pointer skill for hosts that discover work via SKILL.md:
 
 ```bash
-easysociable install --skills content --yes
+easysociable install --skills content,template,slideshow --yes
 ```
 
-Lazy-auth guidance for Agents lives in the package at `skills/ONBOARDING.md`
-(also installed into your host skills directory by `easysociable install`).
+Lazy-auth guidance lives in the package at `skills/ONBOARDING.md`.
+
+## Content Engine
+
+| Command | Purpose |
+|---------|---------|
+| `easysociable engine init [--root] [--yes] [--serve]` | Scaffold starter (never overwrites) |
+| `easysociable engine serve [--engine] [--no-open]` | Build + start workbench on `:8765` |
+| `easysociable engine build [--engine]` | Rebuild `workbench/index.html` |
+| `easysociable engine detect` | Find engines under search roots |
+| `easysociable engine validate --root …` | Starter completeness |
+| `easysociable engine validate --run …` | Run / pack checks before render |
+
+Default `--root` / `--engine` parent is `/workspace` when that directory exists, otherwise the current working directory.
 
 ## Authentication
 
@@ -38,23 +53,19 @@ easysociable templates list --json
 easysociable mcp serve --transport stdio
 ```
 
-Human-readable diagnostics go to stderr. With `--json`, stdout is only the
-versioned JSON envelope.
-
-## Common commands
+## Other commands
 
 | Command | Purpose |
 |---------|---------|
 | `easysociable install [--yes] [--skills list]` | Install Skills + MCP |
 | `easysociable update [--yes] [--skills list]` | Update Skills + MCP |
-| `easysociable auth login --api-key <key>` | Store Gateway credentials |
 | `easysociable templates …` | Page Template drafts / catalog |
-| `easysociable slideshows …` | Temporary Slideshow Runs |
+| `easysociable brands …` | Workspace Brands |
+| `easysociable slideshows …` | Slideshow Runs |
 | `easysociable renders …` | Single-page final render jobs |
 | `easysociable mcp serve --transport stdio` | Unified MCP server |
 
-`--skills` accepts comma-separated short names: `content`, `template`,
-`slideshow` (default: `template,slideshow`).
+`--skills` accepts: `content`, `template`, `slideshow` (default: `template,slideshow`).
 
 ## License
 

package/content-engine/fixtures/golden-run-en/draft.md

@@ -0,0 +1,13 @@
+# Draft
+
+## Page 1 (hook)
+Stop scrolling — this changed my mornings.
+
+## Page 2 (value)
+Wake at the same time, even on weekends.
+
+## Page 3 (value)
+No phone for the first 20 minutes after waking.
+
+## Page 4 (cta)
+Save this and try it tomorrow.

package/content-engine/fixtures/golden-run-en/idea.md

@@ -0,0 +1,26 @@
+---
+run_id: RUN-20260823-morning-routine-tips
+status: pack-ready
+created: 2026-08-23
+---
+
+# Idea
+
+- **one_liner:** Three morning habits that calm the start of the day
+- **account:** your-handle
+- **profile:** default
+- **pillar:** P1
+- **primary_platform:** tiktok
+- **platforms:** tiktok
+- **topic_id:** none
+- **capture_ids:** none
+- **swipe_id:** none
+- **atoms:** none
+- **claim_id:** none
+- **hypothesis:** none
+
+## Platform (this run)
+
+| platform | copy | images (pack) | publish status |
+|----------|------|---------------|----------------|
+| tiktok | yes | yes | pending |

package/content-engine/fixtures/golden-run-en/pack-tiktok.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": "content-pack.v1",
+  "platform": "tiktok",
+  "title": "Three morning habits",
+  "pages": [
+    { "role": "hook", "pageTemplateId": "tpl_hook_001", "slots": { "text_0": "Stop scrolling — this changed my mornings" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "Wake at the same time", "text_1": "Even on weekends" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "No phone for 20 minutes", "text_1": "Before email or feeds" } },
+    { "role": "cta", "pageTemplateId": "tpl_cta_001", "slots": { "text_0": "Save this for tomorrow" } }
+  ]
+}

package/content-engine/scripts/contracts.mjs

@@ -0,0 +1,183 @@
+/** ponytail: mirrors @easysociable/template-public-contracts — upgrade by diffing that package */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, basename } from 'node:path'
+
+export const PAGE_ROLES = [
+  'cover', 'hook', 'setup', 'context', 'value', 'point', 'checklist', 'proof',
+  'evidence', 'compare', 'screenshot', 'metric', 'quote', 'steps', 'cta', 'follow', 'recap',
+]
+
+export const PACK_PLATFORMS = ['tiktok', 'xiaohongshu', 'instagram', 'linkedin', 'threads']
+
+export const SLIDESHOW_PLATFORMS = ['tiktok', 'instagram', 'linkedin', 'threads']
+
+export const PLATFORM_CAPS = {
+  tiktok: { hardMin: 4, hardMax: 35 },
+  xiaohongshu: { hardMin: 2, hardMax: 18 },
+  instagram: { hardMin: 2, hardMax: 20 },
+  linkedin: { hardMin: 2, hardMax: 300 },
+  threads: { hardMin: 2, hardMax: 20 },
+}
+
+const FORBIDDEN_PACK_KEYS = ['deck_template_id', 'deckTemplateId']
+
+const PACK_KEYS = new Set(['schemaVersion', 'platform', 'title', 'pages'])
+const PAGE_KEYS = new Set(['pageTemplateId', 'role', 'slots'])
+export const RUN_FILE_STATUSES = [
+  'RUN_OPEN', 'BRIEF_WAIT', 'DRAFTED', 'EDIT_WAIT', 'SCORED',
+  'READY_TO_POST', 'PUBLISHED', 'HOLD', 'KILLED', 'SUPERSEDED',
+]
+export const RUN_INDEX_STATUSES = [
+  'open', 'brief', 'draft', 'scored', 'ready', 'published', 'hold', 'killed', 'superseded', 'partial',
+]
+const RUN_STATUSES = [
+  ...RUN_FILE_STATUSES,
+  ...RUN_INDEX_STATUSES,
+  'template-ready', 'pack-ready', 'handed-off', 'exported',
+]
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function pushForbidden(errors, value, path) {
+  const text = JSON.stringify(value).toLowerCase()
+  for (const key of FORBIDDEN_PACK_KEYS) {
+    if (text.includes(key.toLowerCase())) errors.push(`${path}: forbidden field ${key}`)
+  }
+}
+
+function pushUnknownKeys(errors, value, allowed, path) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) errors.push(`${path}: unknown field ${key}`)
+  }
+}
+
+function isPublicSlotValue(value) {
+  return value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+}
+
+export function validateContentPack(pack, options = {}) {
+  const { platform: expectedPlatform } = options
+  const errors = []
+  const warnings = []
+
+  if (!isRecord(pack)) {
+    errors.push('pack: must be a JSON object')
+    return { valid: false, errors, warnings }
+  }
+
+  pushForbidden(errors, pack, 'pack')
+  pushUnknownKeys(errors, pack, PACK_KEYS, 'pack')
+
+  if (pack.schemaVersion !== 'content-pack.v1') errors.push('schemaVersion: must be content-pack.v1')
+  if (!PACK_PLATFORMS.includes(pack.platform)) {
+    errors.push(`platform: must be one of ${PACK_PLATFORMS.join(', ')}`)
+  }
+  if (expectedPlatform && pack.platform !== expectedPlatform) {
+    errors.push(`platform: expected ${expectedPlatform}, got ${pack.platform}`)
+  }
+  if (pack.title !== undefined && typeof pack.title !== 'string') errors.push('title: must be a string')
+  if (!Array.isArray(pack.pages) || pack.pages.length === 0) {
+    errors.push('pages: must be a non-empty array')
+    return { valid: errors.length === 0, errors, warnings }
+  }
+
+  const cap = PLATFORM_CAPS[pack.platform]
+  if (cap && (pack.pages.length < cap.hardMin || pack.pages.length > cap.hardMax)) {
+    errors.push(`pages: ${pack.platform} requires ${cap.hardMin}-${cap.hardMax} pages, got ${pack.pages.length}`)
+  }
+
+  pack.pages.forEach((page, index) => {
+    const label = `pages[${index}]`
+    if (!isRecord(page)) {
+      errors.push(`${label}: must be an object`)
+      return
+    }
+    pushUnknownKeys(errors, page, PAGE_KEYS, label)
+    if (!PAGE_ROLES.includes(page.role)) errors.push(`${label}.role: invalid page role`)
+    if (typeof page.pageTemplateId !== 'string' || page.pageTemplateId.length === 0) {
+      errors.push(`${label}.pageTemplateId: required and must be a non-empty string`)
+    }
+    if (!isRecord(page.slots)) {
+      errors.push(`${label}.slots: must be an object`)
+    }
+    else {
+      for (const [key, value] of Object.entries(page.slots)) {
+        if (!isPublicSlotValue(value)) errors.push(`${label}.slots.${key}: must be string, number, boolean or null`)
+      }
+    }
+  })
+
+  if (!SLIDESHOW_PLATFORMS.includes(pack.platform)) {
+    warnings.push(`platform ${pack.platform}: not supported by easysociable-slideshow in V1`)
+  }
+
+  return { valid: errors.length === 0, errors, warnings }
+}
+
+export function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return {}
+  const fields = {}
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    const key = line.slice(0, idx).trim()
+    const value = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, '')
+    if (key) fields[key] = value
+  }
+  return fields
+}
+
+export function ideaField(text, name) {
+  const match = text.match(new RegExp(`\\*\\*${name}:\\*\\*\\s*(.+)`, 'i'))
+  return match ? match[1].trim() : ''
+}
+
+export function validateRunLayout(runDir, options = {}) {
+  const { requirePack = false } = options
+  const errors = []
+  const warnings = []
+  const files = { ideaMd: false, draftMd: false, packMd: false, packs: [] }
+  const ideaPath = join(runDir, 'idea.md')
+
+  if (!existsSync(runDir) || !statSync(runDir).isDirectory()) {
+    errors.push('run: directory required')
+    return { valid: false, errors, warnings, files, frontmatter: {} }
+  }
+  if (!existsSync(ideaPath)) {
+    errors.push('idea.md: required')
+    return { valid: false, errors, warnings, files, frontmatter: {} }
+  }
+
+  files.ideaMd = true
+  const ideaText = readFileSync(ideaPath, 'utf8')
+  const frontmatter = parseFrontmatter(ideaText)
+  const platform = (frontmatter.platform || ideaField(ideaText, 'primary_platform') || ideaField(ideaText, 'platforms')).replace(/\s.*/, '')
+  frontmatter.platform = platform
+  frontmatter.slug = frontmatter.slug || basename(runDir)
+  if (!frontmatter.run_id) errors.push('idea.md frontmatter: missing run_id')
+  if (!frontmatter.status) errors.push('idea.md frontmatter: missing status')
+  if (frontmatter.status && !RUN_STATUSES.includes(frontmatter.status)) {
+    errors.push(`idea.md status: must be one of the engine run statuses`)
+  }
+  if (!platform) warnings.push('idea.md: primary_platform recommended')
+
+  files.draftMd = existsSync(join(runDir, 'draft.md'))
+  files.packMd = existsSync(join(runDir, 'pack.md')) || readdirSync(runDir).some((name) => /^pack-[a-z0-9_-]+\.md$/i.test(name))
+  if (!files.draftMd) warnings.push('draft.md: recommended')
+
+  files.packs = readdirSync(runDir).filter((name) => /^pack-[a-z0-9_-]+\.json$/i.test(name))
+  const slideshowRun = SLIDESHOW_PLATFORMS.includes(platform) || platform === 'ig'
+  const expectedPack = platform === 'ig' ? 'pack-instagram.json' : (platform ? `pack-${platform}.json` : 'pack-<platform>.json')
+  if (requirePack && files.packs.length === 0) {
+    errors.push(`${expectedPack}: required for slideshow handoff`)
+  }
+  if (!slideshowRun && files.packs.length > 0) {
+    errors.push('pack-<platform>.json: only slideshow platforms may contain a Content Pack')
+  }
+
+  return { valid: errors.length === 0, errors, warnings, files, frontmatter }
+}

package/content-engine/scripts/export-contracts.mjs

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { createHash } from 'node:crypto'
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+export function validateExportDirectory(exportDir, options = {}) {
+  const expectedPages = options.expectedPages
+  const errors = []
+  const warnings = []
+  const files = { manifest: false, pngs: [] }
+
+  if (!existsSync(exportDir) || !statSync(exportDir).isDirectory()) {
+    return { valid: false, errors: ['export: directory required'], warnings, files }
+  }
+
+  const manifestPath = join(exportDir, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    errors.push('manifest.json: required')
+    return { valid: false, errors, warnings, files }
+  }
+  files.manifest = true
+
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  }
+  catch (error) {
+    errors.push(`manifest.json: invalid JSON (${error instanceof Error ? error.message : String(error)})`)
+    return { valid: false, errors, warnings, files }
+  }
+  if (!isRecord(manifest)) errors.push('manifest.json: must contain an object')
+
+  const entries = Array.isArray(manifest?.pages)
+    ? manifest.pages
+    : Array.isArray(manifest?.artifacts) ? manifest.artifacts : []
+  if (entries.length === 0) errors.push('manifest.json: pages or artifacts must be a non-empty array')
+
+  files.pngs = readdirSync(exportDir).filter(name => /^\d{2}(?:-[^/]+)?\.png$/i.test(name) && statSync(join(exportDir, name)).isFile())
+  if (entries.length > 0 && files.pngs.length !== entries.length) {
+    errors.push(`export: manifest has ${entries.length} page(s), found ${files.pngs.length} PNG file(s)`)
+  }
+  if (Number.isInteger(expectedPages) && expectedPages > 0 && entries.length !== expectedPages) {
+    errors.push(`export: expected ${expectedPages} page(s), manifest has ${entries.length}`)
+  }
+
+  const pngByName = new Map(files.pngs.map(name => [name, name]))
+  entries.forEach((entry, index) => {
+    if (!isRecord(entry)) {
+      errors.push(`manifest[${index}]: must be an object`)
+      return
+    }
+    const file = typeof entry.file === 'string' && entry.file.length > 0
+      ? basename(entry.file)
+      : `${String(index + 1).padStart(2, '0')}.png`
+    if (file !== entry.file && entry.file !== undefined) errors.push(`manifest[${index}].file: must be a local basename`)
+    if (!pngByName.has(file)) {
+      errors.push(`manifest[${index}].file: missing ${file}`)
+      return
+    }
+    const bytes = readFileSync(join(exportDir, file))
+    if (bytes.length === 0) errors.push(`${file}: empty file`)
+    if (bytes.length < 8 || bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a') {
+      errors.push(`${file}: not a PNG file`)
+    }
+    if (entry.sha256 && entry.sha256 !== sha256(bytes)) errors.push(`${file}: sha256 mismatch`)
+  })
+
+  return { valid: errors.length === 0, errors, warnings, files, manifest }
+}

package/content-engine/scripts/fixture.test.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const root = new URL('..', import.meta.url).pathname
+const goldenRun = join(root, 'fixtures/golden-run-en')
+const validateRun = join(root, 'scripts/validate-run.mjs')
+const validatePack = join(root, 'scripts/validate-pack.mjs')
+
+const packFile = join(goldenRun, 'pack-tiktok.json')
+const packCli = spawnSync(process.execPath, [validatePack, '--file', packFile, '--platform', 'tiktok', '--json'], { encoding: 'utf8' })
+assert.equal(packCli.status, 0, packCli.stdout + packCli.stderr)
+
+const runCli = spawnSync(process.execPath, [validateRun, '--run', goldenRun, '--require-pack', '--json'], { encoding: 'utf8' })
+assert.equal(runCli.status, 0, runCli.stdout + runCli.stderr)
+const runReport = JSON.parse(runCli.stdout)
+assert.equal(runReport.valid, true)
+assert.equal(runReport.layout.frontmatter.status, 'pack-ready')
+
+const pack = JSON.parse(readFileSync(packFile, 'utf8'))
+assert.equal(pack.pages.length, 4)
+
+console.log('Golden fixture validation passed.')

package/content-engine/scripts/starter.mjs

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const ENGINE_ROOT = 'Content Engine'
+export const STARTER_DIR = fileURLToPath(new URL('../starter/', import.meta.url))
+export const WORKBENCH_SRC = fileURLToPath(new URL('../workbench/', import.meta.url))
+export const WORKBENCH_FILES = ['template.html', 'build.py', 'serve.py']
+
+export const ENGINE_PATHS = {
+  runs: 'runs',
+  exports: 'exports',
+  topics: 'topics',
+  discovery: 'discovery',
+  swipe: 'swipe',
+  profiles: 'profiles',
+  inbox: 'inbox',
+  accounts: 'accounts',
+  raw: 'raw',
+  published: 'published',
+  wiki: 'wiki',
+  platforms: 'platforms',
+  workbench: 'workbench',
+}
+
+export function engineJson() {
+  return `${JSON.stringify({
+    schemaVersion: 'content-engine.v1',
+    locale: 'en',
+    root: ENGINE_ROOT,
+    paths: ENGINE_PATHS,
+  }, null, 2)}\n`
+}
+
+function walkFiles(dir) {
+  const out = []
+  if (!existsSync(dir)) return out
+  for (const name of readdirSync(dir)) {
+    if (name === '.DS_Store') continue
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) out.push(...walkFiles(path))
+    else out.push(path)
+  }
+  return out
+}
+
+export function filesFor() {
+  const files = {}
+  for (const path of walkFiles(STARTER_DIR)) {
+    const relativePath = relative(STARTER_DIR, path).split('\\').join('/')
+    files[relativePath] = readFileSync(path, 'utf8')
+  }
+  files['engine.json'] = engineJson()
+  return files
+}

package/content-engine/scripts/validate-export.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { resolve } from 'node:path'
+import { validateExportDirectory } from './export-contracts.mjs'
+
+function parseArgs(argv) {
+  const options = { exportDir: '', expectedPages: undefined, json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--export') options.exportDir = argv[++i] ?? ''
+    else if (arg === '--expected-pages') options.expectedPages = Number(argv[++i])
+    else if (arg === '--json') options.json = true
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else throw new Error(`Unknown argument: ${arg}`)
+  }
+  return options
+}
+
+function output(value, json) {
+  process.stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : `${value.message ?? value}\n`)
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    output({ usage: 'node validate-export.mjs --export <export-dir> [--expected-pages N] [--json]' }, false)
+    process.exit(0)
+  }
+  if (!options.exportDir) {
+    output({ code: 'EXPORT_REQUIRED', message: 'Pass --export <export-dir>.', valid: false }, options.json)
+    process.exitCode = 2
+  }
+  else {
+    const report = validateExportDirectory(resolve(options.exportDir), { expectedPages: options.expectedPages })
+    output({ ...report, action: 'validated', export: resolve(options.exportDir) }, options.json)
+    if (!report.valid) process.exitCode = 2
+  }
+}
+catch (error) {
+  output({ code: 'EXPORT_VALIDATE_FAILED', message: error instanceof Error ? error.message : String(error), valid: false }, true)
+  process.exitCode = 1
+}

package/content-engine/scripts/validate-pack.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { validateContentPack } from './contracts.mjs'
+
+function parseArgs(argv) {
+  const options = { file: '', platform: '', requirePageTemplateId: false, json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--file') options.file = argv[++i] ?? ''
+    else if (arg === '--platform') options.platform = argv[++i] ?? ''
+    else if (arg === '--require-page-template-id') options.requirePageTemplateId = true
+    else if (arg === '--json') options.json = true
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else throw new Error(`Unknown argument: ${arg}`)
+  }
+  return options
+}
+
+function output(value, json) {
+  process.stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : `${value.message ?? value}\n`)
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    output({ usage: 'node validate-pack.mjs --file <pack.json> [--platform tiktok] [--require-page-template-id] [--json]' }, false)
+    process.exit(0)
+  }
+  if (!options.file) {
+    output({ code: 'FILE_REQUIRED', message: 'Pass --file <pack.json>.', valid: false }, options.json)
+    process.exitCode = 2
+  }
+  else {
+    const pack = JSON.parse(readFileSync(resolve(options.file), 'utf8'))
+    const report = validateContentPack(pack, {
+      requirePageTemplateId: options.requirePageTemplateId,
+      platform: options.platform || undefined,
+    })
+    output({ ...report, action: 'validated', file: resolve(options.file) }, options.json)
+    if (!report.valid) process.exitCode = 2
+  }
+}
+catch (error) {
+  output({ code: 'PACK_VALIDATE_FAILED', message: error instanceof Error ? error.message : String(error), valid: false }, true)
+  process.exitCode = 1
+}

package/content-engine/scripts/validate-run.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { validateContentPack, validateRunLayout } from './contracts.mjs'
+import { validateExportDirectory } from './export-contracts.mjs'
+
+function parseArgs(argv) {
+  const options = { run: '', exportDir: '', requirePack: false, requireExport: false, requirePageTemplateId: false, json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--run') options.run = argv[++i] ?? ''
+    else if (arg === '--export') options.exportDir = argv[++i] ?? ''
+    else if (arg === '--require-pack') options.requirePack = true
+    else if (arg === '--require-export') options.requireExport = true
+    else if (arg === '--require-page-template-id') options.requirePageTemplateId = true
+    else if (arg === '--json') options.json = true
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else throw new Error(`Unknown argument: ${arg}`)
+  }
+  return options
+}
+
+function output(value, json) {
+  process.stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : `${value.message ?? value}\n`)
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    output({ usage: 'node validate-run.mjs --run <run-dir> [--require-pack] [--require-export] [--export <export-dir>] [--json]' }, false)
+    process.exit(0)
+  }
+  if (!options.run) {
+    output({ code: 'RUN_REQUIRED', message: 'Pass --run <run-dir>.', valid: false }, options.json)
+    process.exitCode = 2
+  }
+  else {
+    const runDir = resolve(options.run)
+    const layout = validateRunLayout(runDir, { requirePack: options.requirePack })
+    const packs = []
+    for (const name of layout.files.packs) {
+      const platform = name.replace(/^pack-/, '').replace(/\.json$/i, '')
+      try {
+        const pack = JSON.parse(readFileSync(join(runDir, name), 'utf8'))
+        packs.push({ file: name, pages: Array.isArray(pack.pages) ? pack.pages.length : 0, ...validateContentPack(pack, {
+          requirePageTemplateId: options.requirePageTemplateId,
+          platform,
+        }) })
+      }
+      catch (error) {
+        packs.push({ file: name, pages: 0, valid: false, errors: [`invalid JSON (${error instanceof Error ? error.message : String(error)})`], warnings: [] })
+      }
+    }
+    const packErrors = packs.flatMap((item) => item.errors.map((e) => `${item.file}: ${e}`))
+    let exportReport
+    const needsExport = options.requireExport || layout.frontmatter.status === 'exported'
+    if (needsExport) {
+      let exportDir = options.exportDir
+      if (!exportDir) {
+        const engineRoot = resolve(runDir, '..', '..')
+        const engineConfig = join(engineRoot, 'engine.json')
+        if (existsSync(engineConfig)) {
+          try {
+            const engine = JSON.parse(readFileSync(engineConfig, 'utf8'))
+            const base = join(engineRoot, engine.paths.exports, layout.frontmatter.slug)
+            const nested = layout.frontmatter.platform ? join(base, layout.frontmatter.platform) : ''
+            exportDir = nested && existsSync(nested) ? nested : base
+          }
+          catch (error) {
+            exportReport = { valid: false, errors: [`engine.json: invalid JSON (${error instanceof Error ? error.message : String(error)})`], warnings: [] }
+          }
+        }
+        else exportReport = { valid: false, errors: ['engine.json: required to derive export path'], warnings: [] }
+      }
+      if (!exportReport) {
+        const expectedPages = packs.find(item => item.pages > 0)?.pages ?? 1
+        exportReport = validateExportDirectory(resolve(exportDir), { expectedPages })
+        exportReport.export = resolve(exportDir)
+      }
+    }
+    const exportErrors = exportReport?.errors?.map(error => `export: ${error}`) ?? []
+    const valid = layout.valid && packErrors.length === 0 && exportErrors.length === 0
+    output({
+      valid,
+      action: 'validated',
+      run: runDir,
+      layout,
+      packs,
+      export: exportReport,
+      errors: [...layout.errors, ...packErrors, ...exportErrors],
+      warnings: [...layout.warnings, ...packs.flatMap((item) => item.warnings.map((w) => `${item.file}: ${w}`)), ...(exportReport?.warnings ?? [])],
+    }, options.json)
+    if (!valid) process.exitCode = 2
+  }
+}
+catch (error) {
+  output({ code: 'RUN_VALIDATE_FAILED', message: error instanceof Error ? error.message : String(error), valid: false }, true)
+  process.exitCode = 1
+}