feat(post-kit-compiler): add @singleton-sd/post-kit-compiler package

packages/post-kit-compiler/LICENSE

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

packages/post-kit-compiler/README.md

@@ -0,0 +1,81 @@
+# @singleton-sd/post-kit-compiler
+
+Template compiler for [PostKit](../../README.md). Reads Git-backed email template source files (`template.json`, `metadata.json`, `preview.json`), validates them, and produces a compiled `CompiledTemplate` artifact for use by `post-kit-publisher` and `apps/api`.
+
+## HTML renderer and variable engine
+
+HTML is produced by [`@usewaypoint/email-builder`](https://www.npmjs.com/package/@usewaypoint/email-builder) `renderToStaticMarkup` (EmailBuilder.js JSON → email HTML).
+
+Subject lines and `{{variable}}` substitution in that HTML use [Handlebars](https://handlebarsjs.com/) `^4.7.8` (the version declared in this package). Handlebars is **not** the HTML renderer.
+
+Until send-time substitution, compiled `templateHtml` keeps Handlebars placeholders. `compile()` still renders preview.json through Handlebars to fail fast on invalid templates.
+
+## Installation
+
+```bash
+pnpm add @singleton-sd/post-kit-compiler
+```
+
+## API
+
+```ts
+import { compile, compileFromDirectory, validateSource, CompilerError } from '@singleton-sd/post-kit-compiler';
+```
+
+### `compile(source, options?)`
+
+Validates and compiles a `TemplateSource` object into a `CompiledTemplate`.
+
+```ts
+const result = await compile({
+  templateJson: { document: { type: 'EmailLayout', data: {} } },
+  metadata: {
+    key: 'marketing.contact-us',
+    name: 'Contact Us',
+    subject: 'New message from {{name}}',
+    variables: ['name', 'email', 'message'],
+    schemaVersion: '1',
+  },
+  previewData: { name: 'Jane Doe', email: 'jane@example.com', message: 'Hello!' },
+});
+
+console.log(result.manifest.contentHash); // SHA-256 hex
+```
+
+### `compileFromDirectory(dir, options?)`
+
+Reads `template.json`, `metadata.json`, and `preview.json` from `dir` and delegates to `compile()`.
+
+```ts
+const result = await compileFromDirectory('./content/email-templates/marketing.contact-us');
+```
+
+### `validateSource(source)`
+
+Dry-run validation — returns `{ ok: true }` or `{ ok: false; errors: string[] }`. Does not throw.
+
+```ts
+const validation = validateSource(source);
+if (!validation.ok) {
+  console.error(validation.errors);
+}
+```
+
+### `CompilerError`
+
+Thrown by `compile()` and `compileFromDirectory()` on validation or render failures. Has a `code` property:
+
+| Code | Meaning |
+|---|---|
+| `INVALID_TEMPLATE_JSON` | `template.json` is missing or not valid JSON |
+| `INVALID_METADATA` | `metadata.json` or `preview.json` is missing, not valid JSON, or fails schema validation |
+| `MISSING_PREVIEW_VARIABLE` | A variable declared in `metadata.variables` is absent from `previewData` |
+| `RENDER_FAILURE` | HTML or subject template rendering failed |
+
+## Development
+
+```bash
+pnpm test   # type-check + run tests
+pnpm build  # emit CommonJS to dist/
+pnpm lint   # covered by root eslint
+```

packages/post-kit-compiler/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@singleton-sd/post-kit-compiler",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Template compiler for PostKit — validates and compiles EmailBuilder.js source files into deployable HTML artifacts",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "pnpm --filter @singleton-sd/post-kit-types run build && tsc -p tsconfig.json",
+    "lint": "echo \"lint:compiler — covered by root eslint on staged files\"",
+    "test": "pnpm --filter @singleton-sd/post-kit-types run build && tsc -p tsconfig.spec.json && node --import tsx --test src/**/*.spec.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.9",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "dependencies": {
+    "@singleton-sd/post-kit-types": "workspace:*",
+    "@usewaypoint/email-builder": "0.0.9",
+    "handlebars": "^4.7.8",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "zod": "^3.25.76"
+  }
+}

packages/post-kit-compiler/src/compiler-error.ts

@@ -0,0 +1,12 @@
+export type CompilerErrorCode =
+  'INVALID_TEMPLATE_JSON' | 'INVALID_METADATA' | 'MISSING_PREVIEW_VARIABLE' | 'RENDER_FAILURE';
+
+export class CompilerError extends Error {
+  constructor(
+    public readonly code: CompilerErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'CompilerError';
+  }
+}