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

packages/post-kit-publisher/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-publisher/README.md

@@ -0,0 +1,91 @@
+# @singleton-sd/post-kit-publisher
+
+Compile Git-backed PostKit email templates and publish runtime artifacts to Azure Blob Storage for `apps/api` TemplateStore.
+
+## Install
+
+```bash
+pnpm add @singleton-sd/post-kit-publisher
+```
+
+## CLI
+
+```bash
+post-kit-publish \
+  --templates ./content/email-templates \
+  --tenant inkads \
+  --environment production \
+  --storage-account ssdpostkitstprodae \
+  --container templates \
+  --commit "$GITHUB_SHA"
+```
+
+Auth uses `DefaultAzureCredential` (Managed Identity in CI, `az login` locally). No connection strings.
+
+Blob layout (must match TemplateStore):
+
+```text
+tenants/{tenant}/{environment}/templates/{templateKey}/template.html
+tenants/{tenant}/{environment}/templates/{templateKey}/metadata.json
+```
+
+If any template fails to compile, the CLI exits non-zero and uploads nothing.
+
+## Library
+
+```ts
+import { publishTemplates } from '@singleton-sd/post-kit-publisher';
+
+const result = await publishTemplates({
+  templatesDir: './content/email-templates',
+  tenant: 'inkads',
+  environment: 'production',
+  storageAccount: 'ssdpostkitstprodae',
+  container: 'templates',
+  commit: process.env.GITHUB_SHA,
+});
+```
+
+## GitHub Actions (OIDC) example
+
+```yaml
+name: Publish email templates
+on:
+  push:
+    paths:
+      - 'content/email-templates/**'
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - uses: azure/login@v2
+        with:
+          client-id: ${{ vars.AZURE_CLIENT_ID }}
+          tenant-id: ${{ vars.AZURE_TENANT_ID }}
+          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+      - run: >
+          pnpm exec post-kit-publish
+          --templates ./content/email-templates
+          --tenant inkads
+          --environment production
+          --storage-account ssdpostkitstprodae
+          --container templates
+          --commit ${{ github.sha }}
+```
+
+## Development
+
+```bash
+pnpm test
+pnpm build
+```

packages/post-kit-publisher/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@singleton-sd/post-kit-publisher",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Compile and publish PostKit email templates to Azure Blob Storage",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "post-kit-publish": "./dist/bin/post-kit-publish.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "pnpm --filter @singleton-sd/post-kit-types run build && pnpm --filter @singleton-sd/post-kit-compiler run build && tsc -p tsconfig.json",
+    "lint": "echo \"lint:publisher — covered by root eslint on staged files\"",
+    "test": "pnpm --filter @singleton-sd/post-kit-types run build && pnpm --filter @singleton-sd/post-kit-compiler run build && tsc -p tsconfig.spec.json && node --import tsx --test src/**/*.spec.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.9",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.13.1",
+    "@azure/storage-blob": "^12.33.0",
+    "@singleton-sd/post-kit-compiler": "workspace:*",
+    "@singleton-sd/post-kit-types": "workspace:*"
+  }
+}

packages/post-kit-publisher/src/bin/post-kit-publish.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { publishTemplates } from '../publish';
+import type { TenantEnvironment } from '@singleton-sd/post-kit-types';
+
+function usage(): never {
+  console.error(`Usage:
+  post-kit-publish \\
+    --templates <dir> \\
+    --tenant <id> \\
+    --environment <development|staging|production> \\
+    --storage-account <name> \\
+    --container <name> \\
+    [--commit <sha>]`);
+  process.exit(2);
+}
+
+function readFlag(argv: string[], name: string): string | undefined {
+  const idx = argv.indexOf(name);
+  if (idx === -1) return undefined;
+  return argv[idx + 1];
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) usage();
+
+  const templates = readFlag(argv, '--templates');
+  const tenant = readFlag(argv, '--tenant');
+  const environment = readFlag(argv, '--environment');
+  const storageAccount = readFlag(argv, '--storage-account');
+  const container = readFlag(argv, '--container');
+  const commit = readFlag(argv, '--commit');
+
+  if (!templates || !tenant || !environment || !storageAccount || !container) {
+    usage();
+  }
+
+  const result = await publishTemplates({
+    templatesDir: templates,
+    tenant,
+    environment: environment as TenantEnvironment,
+    storageAccount,
+    container,
+    commit,
+  });
+
+  if (result.failed.length > 0) {
+    for (const failure of result.failed) {
+      console.error(`FAILED ${failure.key}: ${failure.error}`);
+    }
+    process.exit(1);
+  }
+
+  console.error(`Published ${result.published.length} template(s): ${result.published.join(', ')}`);
+}
+
+main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

packages/post-kit-publisher/src/index.ts

@@ -0,0 +1,8 @@
+export { publishTemplates, type PublishOptions, type PublishResult } from './publish';
+export {
+  assertSafeTenantId,
+  assertSafeEnvironment,
+  assertSafeTemplateKey,
+  assertSafeStorageAccount,
+  blobBasePath,
+} from './path-safety';

packages/post-kit-publisher/src/path-safety.ts

@@ -0,0 +1,55 @@
+import type { TenantEnvironment } from '@singleton-sd/post-kit-types';
+
+const SAFE_SEGMENT = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+const SAFE_TEMPLATE_KEY = /^[a-zA-Z0-9._-]+$/;
+/** Azure Storage account names: 3–24 lowercase letters and digits. */
+const SAFE_STORAGE_ACCOUNT = /^[a-z0-9]{3,24}$/;
+const ENVIRONMENTS = new Set<TenantEnvironment>(['development', 'staging', 'production']);
+
+export function assertSafeTenantId(tenant: string): void {
+  if (!tenant || !SAFE_SEGMENT.test(tenant) || tenant.includes('..')) {
+    throw new Error(
+      `Invalid tenant "${tenant}". Use alphanumeric characters and hyphens only (no path segments).`,
+    );
+  }
+}
+
+export function assertSafeEnvironment(
+  environment: string,
+): asserts environment is TenantEnvironment {
+  if (!ENVIRONMENTS.has(environment as TenantEnvironment)) {
+    throw new Error(
+      `Invalid environment "${environment}". Must be one of: development, staging, production.`,
+    );
+  }
+}
+
+export function assertSafeTemplateKey(templateKey: string): void {
+  if (
+    !templateKey ||
+    templateKey === '.' ||
+    templateKey === '..' ||
+    !SAFE_TEMPLATE_KEY.test(templateKey)
+  ) {
+    throw new Error(
+      `Invalid template key "${templateKey}". Must match /^[a-zA-Z0-9._-]+$/ and must not be "." or "..".`,
+    );
+  }
+}
+
+export function assertSafeStorageAccount(storageAccount: string): void {
+  if (!SAFE_STORAGE_ACCOUNT.test(storageAccount)) {
+    throw new Error(`Invalid storage account "${storageAccount}". Must match /^[a-z0-9]{3,24}$/.`);
+  }
+}
+
+export function blobBasePath(
+  tenant: string,
+  environment: TenantEnvironment,
+  templateKey: string,
+): string {
+  assertSafeTenantId(tenant);
+  assertSafeEnvironment(environment);
+  assertSafeTemplateKey(templateKey);
+  return `tenants/${tenant}/${environment}/templates/${templateKey}`;
+}