@hedwigjs/create-registry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hedwig contributors
+
+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.

package/README.md

@@ -0,0 +1,283 @@
+# @hedwigjs/create-registry
+
+Optional starter kit. Scaffolds an opinionated topics-registry
+workspace for `@hedwigjs/broker` — a codegen-driven TypeScript package
+where each event lives in its own file and the runtime types
+(`Topic`, `TopicPayloads`, `TOPICS`, `registry`) are generated for you.
+
+```bash
+# planned CLI, not yet published to npm:
+npm create @hedwigjs/registry my-topics
+```
+
+> `@hedwigjs/broker` accepts topics from **any source** — Zod,
+> Protobuf, GraphQL, a hand-written `TopicMap`, or a mix. This package
+> is a convenience layer for teams starting fresh in TypeScript. If
+> you already have a contracts pipeline, keep it — see
+> [Bring your own contracts](../../docs/content/guides/bring-your-own-contracts.md).
+
+> Pre-release (`0.1.0`, private). Not yet published to npm.
+
+**Full project docs & reference stand →** [`../..#readme`](../..#readme)
+
+---
+
+## Table of contents
+
+- [What it does](#what-it-does)
+- [Usage](#usage)
+- [What gets generated](#what-gets-generated)
+- [The `EventContract` shape](#the-eventcontract-shape)
+- [Generated exports](#generated-exports)
+- [Using the registry in your app](#using-the-registry-in-your-app)
+- [Adding an event](#adding-an-event)
+- [Versioning workflow](#versioning-workflow)
+- [When to use — and when not to](#when-to-use--and-when-not-to)
+- [License](#license)
+
+---
+
+## What it does
+
+Running the initializer creates a standalone TypeScript package with:
+
+- A file convention: one event per file at `src/domains/<domain>/<action>.v<N>.ts`.
+- A tiny `EventContract<Name, Payload>` type.
+- A codegen (`scripts/build.mjs`) that scans `src/domains/`, validates
+  names, and writes `src/index.generated.ts` — a composed registry
+  plus the exact `Topic` / `TopicPayloads` types `@hedwigjs/broker`
+  expects, and a `TOPICS` constant map you can use to avoid string
+  typos at call sites.
+
+The generated package has **no runtime dependency on `@hedwigjs/*`** —
+it's a plain TS package that ships types and (optional) fixture
+payloads. Consumers can be broker clients, custom pub/sub, tests, or
+docs generators.
+
+---
+
+## Usage
+
+```bash
+npm create @hedwigjs/registry <directory> [options]
+```
+
+Interactive by default. Pre-supply flags to skip prompts.
+
+| Flag                  | Purpose                                                              |
+| --------------------- | -------------------------------------------------------------------- |
+| `<directory>`         | Positional. Target directory for the new package.                    |
+| `--name <name>`       | npm package name (e.g. `@my-org/topics`). Asked interactively if omitted. |
+| `--install`           | Run `npm install` in the created directory after scaffold.           |
+| `--no-install`        | Skip install.                                                         |
+| `--yes`, `-y`         | Accept all defaults. Requires `<directory>` positional.              |
+| `--force`, `-f`       | Overwrite a non-empty target directory.                              |
+| `--help`, `-h`        | Show help.                                                            |
+
+```bash
+# interactive
+npm create @hedwigjs/registry my-topics
+
+# fully non-interactive
+npm create @hedwigjs/registry my-topics --name @my-org/topics --yes
+```
+
+The initializer auto-detects the workspace's package manager
+(`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and
+delegates the install to it.
+
+---
+
+## What gets generated
+
+```
+my-topics/
+├── package.json
+├── tsconfig.json
+├── .gitignore
+├── scripts/
+│   └── build.mjs             # codegen: scans src/domains → writes src/index.generated.ts
+└── src/
+    ├── index.ts              # re-exports index.generated (don't edit)
+    ├── index.generated.ts    # AUTO-GENERATED — never hand-edit
+    ├── domains/              # your event contracts live here
+    └── lib/
+        └── contract.ts       # EventContract<Name, Payload> type (don't edit)
+```
+
+Scripts in the generated package:
+
+| Script            | What it does                                            |
+| ----------------- | ------------------------------------------------------- |
+| `npm run build`   | Codegen + `tsc`. Emits `dist/` ready to publish.        |
+| `npm run dev`     | Watch codegen + `tsc --watch` in parallel.              |
+| `prepublishOnly`  | Runs `npm run build` before `npm publish`.              |
+
+---
+
+## The `EventContract` shape
+
+Each event file exports a `default` object that `satisfies`
+`EventContract`. Codegen imports every event by default export, so
+**named exports won't be picked up** — always use `export default`.
+
+```ts
+// src/domains/notification/show.v1.ts
+import type { EventContract } from "../../lib/contract";
+
+export default {
+  name: "notification.show.v1",
+  description: "Show a toast notification.",
+  payload: {} as {
+    kind: "success" | "info" | "warn" | "error";
+    title: string;
+    body?: string;
+  },
+  examples: {
+    happy: { kind: "success", title: "Order accepted" },
+    error: { kind: "error", title: "Payment failed" },
+  },
+} satisfies EventContract;
+```
+
+Fields:
+
+| Field            | Required | Purpose                                                                                     |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `name`           | yes      | Topic string. Must match the path: `<domain>/<action>.v<N>.ts` → `"<domain>.<action>.v<N>"`. |
+| `description`    | yes      | Human-readable. Shown in DevTools and hover cards.                                          |
+| `payload`        | yes      | Payload type. Idiomatic: `{} as { ... }`.                                                   |
+| `examples`       | yes      | Named fixtures. `examples.happy` is the default seed used by DevTools' Debug tab.           |
+| `deprecatedBy`   | no       | Successor topic name. DevTools surfaces a warning.                                          |
+| `observability`  | no       | Mark telemetry-only topics so `NACK NO_SUBSCRIBERS` renders neutrally instead of red.       |
+
+The path-to-name convention is enforced by codegen — a mismatch fails
+the build with an explicit error.
+
+---
+
+## Generated exports
+
+Codegen writes `src/index.generated.ts` and `src/index.ts` re-exports
+it. Consumers get four exports from the package root:
+
+```ts
+import { registry, TOPICS, type Topic, type TopicPayloads } from "@my-org/topics";
+```
+
+| Export           | Kind    | Purpose                                                                                          |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `Topic`          | type    | String union of every topic. Drop into `createClient<Topic, TopicPayloads>('id')`.                |
+| `TopicPayloads`  | type    | `{ [topic]: payload }` map. Drop into `initBroker<Topic, TopicPayloads>({...})`.                   |
+| `TOPICS`         | value   | SCREAMING_SNAKE_CASE constants like `TOPICS.CART_ITEM_ADDED_V1 === "cart.item-added.v1"`.          |
+| `registry`       | value   | Full `Record<name, EventContract>`. Pass to `<MessageBrokerDevTools registry={registry} />`.      |
+
+Each event is also importable directly by path — useful when you only
+need one contract:
+
+```ts
+import CartItemAdded from "@my-org/topics/domains/cart/item-added.v1";
+
+cartClient.emit(CartItemAdded.name, { sku: "CROISSANT", qty: 2 });
+```
+
+---
+
+## Using the registry in your app
+
+Boot the broker with the generated types:
+
+```ts
+import { initBroker, createClient } from "@hedwigjs/broker";
+import type { Topic, TopicPayloads } from "@my-org/topics";
+
+initBroker<Topic, TopicPayloads>({ history: { enabled: true, maxSize: 200 } });
+
+const cartClient = createClient<Topic, TopicPayloads>("cart");
+```
+
+Rename a topic in one place, and every `emit` / `on` / `request` in
+your codebase lights up in TypeScript.
+
+Wire the registry into DevTools for autocomplete and payload prefill:
+
+```tsx
+import { getBroker } from "@hedwigjs/broker";
+import { MessageBrokerDevTools } from "@hedwigjs/devtools";
+import { registry } from "@my-org/topics";
+
+<MessageBrokerDevTools broker={getBroker()} registry={registry} />
+```
+
+`EventContract` is structurally compatible with the
+`TopicContractInfo` shape DevTools consumes — no adapter needed.
+
+Use `TOPICS` at call sites when you'd rather have autocomplete than
+string literals:
+
+```ts
+cartClient.emit(TOPICS.CART_ITEM_ADDED_V1, { sku: "CROISSANT", qty: 2 });
+```
+
+---
+
+## Adding an event
+
+1. Create `src/domains/<domain>/<action>.v1.ts` — one event per file.
+2. Fill in `name` (must match the path), `description`, `payload`,
+   and at least an `examples.happy` fixture.
+3. `npm run dev` picks it up automatically; `npm run build` produces
+   the final `dist/`.
+
+Path convention (enforced by codegen):
+
+- `<domain>` and `<action>` are kebab-case: `[a-z][a-z0-9-]*`.
+- Nesting depth is exactly one: `src/domains/<domain>/<file>.ts`.
+- File name matches `<action>.v<N>.ts`.
+
+Violations fail the build with an explicit message.
+
+---
+
+## Versioning workflow
+
+Topics are versioned in the name (`.v1`, `.v2`, …). When a contract
+must change in a breaking way:
+
+1. Copy `src/domains/<domain>/<action>.v1.ts` → `<action>.v2.ts`.
+2. Update `name` to `<domain>.<action>.v2` and revise the payload.
+3. In `<action>.v1.ts` add `deprecatedBy: "<domain>.<action>.v2"`.
+4. `npm run build`.
+
+Both versions ship side by side in the generated registry. Consumers
+migrate at their own pace; DevTools shows the deprecation warning on
+every v1 message so nothing rots silently.
+
+---
+
+## When to use — and when not to
+
+**Use `@hedwigjs/create-registry` when:**
+
+- Greenfield TS project, no existing contract pipeline.
+- You want DevTools autocomplete + payload examples out of the box.
+- You value the enforced path/name convention for grep-ability.
+
+**Use your own pipeline when:**
+
+- Contracts are already generated (Zod, Protobuf, GraphQL codegen,
+  OpenAPI, hand-written `TopicMap`).
+- Non-TS producers publish to the same broker — the source of truth
+  lives outside TypeScript.
+- You want a different file layout or naming convention.
+
+In both cases, `@hedwigjs/broker` accepts your `Topic` +
+`TopicPayloads` types as generic parameters. Nothing forces the
+starter — see
+[Bring your own contracts](../../docs/content/guides/bring-your-own-contracts.md).
+
+---
+
+## License
+
+MIT.

package/dist/index.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * @hedwigjs/create-registry — initializer entry point.
+ *
+ * Invoked via `npm create @hedwigjs/registry [<directory>] [options]`.
+ *
+ * Pipeline:
+ *  1. parseArgs(argv) — extract <directory> and flags
+ *  2. runPrompts()    — interactive UX (or accept pre-supplied)
+ *  3. validate target — check existence/empty/--force
+ *  4. copyTemplates() — walk templates/, substitute placeholders
+ *  5. (optional) npm install
+ *  6. print next-step instructions
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { runPrompts, confirm } from "./prompts.js";
+// ────────────────────────────────────────────────────────────────────
+// Locate templates/ relative to the compiled bin
+// ────────────────────────────────────────────────────────────────────
+//
+// This file (compiled) lives at <pkg>/dist/index.js
+// templates/ lives at      <pkg>/templates/
+// → relative path is ../templates
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = resolve(__dirname, "..", "templates");
+function parseArgs(argv) {
+    const opts = { yes: false, force: false };
+    let i = 0;
+    // First positional → directory
+    if (argv[0] && !argv[0].startsWith("-")) {
+        opts.directory = argv[0];
+        i = 1;
+    }
+    for (; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--name":
+                opts.packageName = argv[++i];
+                if (!opts.packageName) {
+                    throw new Error("--name requires a value");
+                }
+                break;
+            case "--install":
+                opts.install = true;
+                break;
+            case "--no-install":
+                opts.install = false;
+                break;
+            case "--yes":
+            case "-y":
+                opts.yes = true;
+                break;
+            case "--force":
+            case "-f":
+                opts.force = true;
+                break;
+            case "--help":
+            case "-h":
+                printHelp();
+                process.exit(0);
+            // eslint-disable-next-line no-fallthrough
+            default:
+                if (arg.startsWith("-")) {
+                    throw new Error(`Unknown flag: ${arg}`);
+                }
+                throw new Error(`Unexpected positional argument: ${arg}`);
+        }
+    }
+    return opts;
+}
+function printHelp() {
+    process.stdout.write(`
+Usage: npm create @hedwigjs/registry [<directory>] [options]
+
+Initializes a new directory as a topics registry package for @hedwigjs/broker.
+Created package is fully self-contained — no runtime dependency on @hedwigjs/*.
+
+Options:
+  --name <name>      Package name (e.g. @your_org/topics). Asked interactively if omitted.
+  --install          Install dependencies after scaffold.
+  --no-install       Skip npm install.
+  --yes, -y          Accept all defaults; combine with positional/--name.
+  --force, -f        Overwrite non-empty target directory.
+  --help, -h         Show this help.
+
+Examples:
+  npm create @hedwigjs/registry hse-topics
+  npm create @hedwigjs/registry hse-topics --name @your-org/topics --yes
+`);
+}
+// ────────────────────────────────────────────────────────────────────
+// Target directory
+// ────────────────────────────────────────────────────────────────────
+function isDirectoryEmpty(path) {
+    try {
+        return readdirSync(path).length === 0;
+    }
+    catch {
+        return true;
+    }
+}
+function clearDirectory(path) {
+    for (const entry of readdirSync(path)) {
+        rmSync(join(path, entry), { recursive: true, force: true });
+    }
+}
+function substitute(content, ctx) {
+    const map = ctx;
+    return content.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+        if (key in map)
+            return map[key];
+        throw new Error(`Unknown placeholder: {{${key}}} in template`);
+    });
+}
+function copyTemplates(srcDir, destDir, ctx) {
+    if (!existsSync(destDir))
+        mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = join(srcDir, entry.name);
+        let destName = entry.name;
+        // Special renames (npm strips .gitignore from published packages)
+        if (destName === "_gitignore")
+            destName = ".gitignore";
+        if (entry.isDirectory()) {
+            copyTemplates(srcPath, join(destDir, destName), ctx);
+            continue;
+        }
+        let content = readFileSync(srcPath, "utf-8");
+        if (destName.endsWith(".tmpl")) {
+            destName = destName.slice(0, -".tmpl".length);
+            content = substitute(content, ctx);
+        }
+        writeFileSync(join(destDir, destName), content);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Package manager detection + install
+// ────────────────────────────────────────────────────────────────────
+function detectPackageManager(startDir) {
+    let dir = startDir;
+    while (true) {
+        if (existsSync(join(dir, "pnpm-lock.yaml")))
+            return "pnpm";
+        if (existsSync(join(dir, "yarn.lock")))
+            return "yarn";
+        if (existsSync(join(dir, "package-lock.json")))
+            return "npm";
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // hit filesystem root
+        dir = parent;
+    }
+    return "npm";
+}
+function runInstall(targetDir) {
+    const pm = detectPackageManager(dirname(targetDir));
+    process.stdout.write(`\nInstalling dependencies with ${pm}...\n`);
+    const result = spawnSync(pm, ["install"], {
+        cwd: targetDir,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+    });
+    if (result.status !== 0) {
+        throw new Error(`${pm} install failed (exit code ${result.status})`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Main
+// ────────────────────────────────────────────────────────────────────
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    const answers = await runPrompts({
+        directory: opts.directory,
+        packageName: opts.packageName,
+        skipPrompts: opts.yes,
+    });
+    const targetDir = resolve(process.cwd(), answers.directory);
+    // Validate target
+    if (existsSync(targetDir) && !isDirectoryEmpty(targetDir)) {
+        if (!opts.force) {
+            throw new Error(`Directory '${answers.directory}' already exists and is not empty.\n` +
+                `  Run with --force to overwrite.`);
+        }
+        clearDirectory(targetDir);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    // Copy templates
+    copyTemplates(TEMPLATES_DIR, targetDir, {
+        PACKAGE_NAME: answers.packageName,
+    });
+    process.stdout.write(`\n✔ Created ${answers.directory}/\n`);
+    // Install dependencies
+    let install = opts.install;
+    if (install === undefined) {
+        install = opts.yes ? true : await confirm("Install dependencies now?", true);
+    }
+    if (install) {
+        runInstall(targetDir);
+    }
+    // Print next steps
+    process.stdout.write(`
+Done! Next steps:
+
+  cd ${answers.directory}
+  ${install ? "" : "npm install\n  "}npm run dev    # watch codegen + tsc
+  # Add an event: create src/domains/<domain>/<action>.v1.ts
+  # (see the generated README for the file template)
+`);
+}
+main().catch((err) => {
+    process.stderr.write(`✗ ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/prompts.js

@@ -0,0 +1,116 @@
+/**
+ * Interactive prompts for create-registry initializer.
+ *
+ * Two prompts:
+ *   1. Directory name (skipped if passed via argv)
+ *   2. Package name   (always asked, default derived from directory name)
+ *
+ * Uses node:readline/promises — no third-party dependency.
+ */
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+const DIRECTORY_PATTERN = /^[a-zA-Z0-9._-]+$/;
+const PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+function validateDirectory(value) {
+    if (!value)
+        return "directory name is required";
+    if (value === "." || value === "..")
+        return "use an explicit directory name";
+    if (value.includes("/") || value.includes("\\"))
+        return "must be a single segment (no path separators)";
+    if (!DIRECTORY_PATTERN.test(value))
+        return `must match ${DIRECTORY_PATTERN}`;
+    return null;
+}
+function validatePackageName(value) {
+    if (!value)
+        return "package name is required";
+    if (!PACKAGE_NAME_PATTERN.test(value))
+        return "invalid npm package name (e.g. @scope/name or just name)";
+    return null;
+}
+function defaultPackageName(directory) {
+    // Most reasonable default: directory name as-is, no scope.
+    // User typically overrides with @org/name.
+    return directory;
+}
+async function ask(rl, question, options) {
+    const { defaultValue, validate } = options;
+    while (true) {
+        const prompt = defaultValue
+            ? `? ${question} (${defaultValue}): `
+            : `? ${question}: `;
+        const raw = await rl.question(prompt);
+        const value = (raw.trim() || defaultValue || "").trim();
+        if (validate) {
+            const error = validate(value);
+            if (error) {
+                process.stdout.write(`  ✗ ${error}\n`);
+                continue;
+            }
+        }
+        return value;
+    }
+}
+export async function runPrompts(input_) {
+    // Resolve directory
+    let directory = input_.directory;
+    if (directory) {
+        const error = validateDirectory(directory);
+        if (error) {
+            throw new Error(`Invalid directory '${directory}': ${error}`);
+        }
+    }
+    // Resolve package name
+    let packageName = input_.packageName;
+    if (packageName) {
+        const error = validatePackageName(packageName);
+        if (error) {
+            throw new Error(`Invalid package name '${packageName}': ${error}`);
+        }
+    }
+    // skipPrompts (--yes) requires both to be pre-supplied or defaulted
+    if (input_.skipPrompts) {
+        if (!directory) {
+            throw new Error("--yes requires <directory> to be passed as positional argument");
+        }
+        if (!packageName) {
+            packageName = defaultPackageName(directory);
+        }
+        return { directory, packageName };
+    }
+    // Interactive mode
+    const rl = createInterface({ input, output });
+    try {
+        if (!directory) {
+            directory = await ask(rl, "Directory name", {
+                validate: validateDirectory,
+            });
+        }
+        if (!packageName) {
+            packageName = await ask(rl, "Package name", {
+                defaultValue: defaultPackageName(directory),
+                validate: validatePackageName,
+            });
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return { directory, packageName };
+}
+export async function confirm(question, defaultYes) {
+    const rl = createInterface({ input, output });
+    try {
+        const def = defaultYes ? "Y/n" : "y/N";
+        const raw = await rl.question(`? ${question} [${def}]: `);
+        const value = raw.trim().toLowerCase();
+        if (!value)
+            return defaultYes;
+        return value.startsWith("y");
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hedwigjs/create-registry",
+  "version": "0.1.0",
+  "description": "Initializer for a Hedwig topics-registry package. Scaffolds a standalone TypeScript workspace with codegen, types, and helpers — no runtime dependency on @hedwigjs/*.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "create-registry": "./dist/index.js"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hedwigjs/hedwig.git",
+    "directory": "packages/create-registry"
+  },
+  "bugs": {
+    "url": "https://github.com/hedwigjs/hedwig/issues"
+  },
+  "homepage": "https://github.com/hedwigjs/hedwig/tree/main/packages/create-registry#readme",
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "hedwig",
+    "topics",
+    "registry",
+    "initializer",
+    "scaffold",
+    "create-package"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

package/templates/README.md.tmpl

@@ -0,0 +1,85 @@
+# {{PACKAGE_NAME}}
+
+Реестр топиков для `@hedwigjs/broker`. Создан через initializer `@hedwigjs/create-registry`.
+
+## Структура
+
+```
+src/
+├── domains/<domain>/<action>.v<N>.ts   ← события, один файл = одно событие
+├── lib/contract.ts                     ← тип EventContract (не трогать)
+├── index.ts                            ← публичный entry (не трогать)
+└── index.generated.ts                  ← агрегат, генерится автоматически
+scripts/
+└── build.mjs                           ← codegen
+```
+
+## Скрипты
+
+| Команда | Что делает |
+|---|---|
+| `npm run dev` | Watch-сборка во время разработки |
+| `npm run build` | Одноразовая сборка перед публикацией |
+
+## Добавление события
+
+1. Скопировать соседний event-файл (или создать новый по шаблону ниже) в `src/domains/<domain>/<action>.v1.ts`:
+
+```ts
+import type { EventContract } from "../../lib/contract";
+
+export default {
+  name: "<domain>.<action>.v1",
+  description: "Описание события",
+
+  payload: {} as {
+    // ...
+  },
+
+  examples: {
+    happy: { /* ... */ },
+  },
+} satisfies EventContract;
+```
+
+2. Поменять `name`, `description`, `payload`, `examples`
+3. `npm run build` (или watch автоматом подхватит)
+
+Конвенция: имя домена и action в `name` **обязательно** должны совпадать с путём — `users/fetched.v1.ts` → `name: "users.fetched.v1"`. Codegen упадёт с ошибкой при расхождении.
+
+## Версионирование
+
+При изменении контракта опубликованного события:
+
+1. Скопировать `<action>.v1.ts` → `<action>.v2.ts`
+2. Поменять `name` на `...v2`
+3. В `<action>.v1.ts` добавить `deprecatedBy: "<domain>.<action>.v2"`
+4. `npm run build`
+
+## Использование в MFE
+
+```ts
+import UsersFetched from "{{PACKAGE_NAME}}/domains/users/fetched.v1";
+
+client.emit(UsersFetched.name, {
+  users: [...],
+  fetchedAt: Date.now(),
+});
+```
+
+## Использование всего реестра (DevTools, типы брокера)
+
+```ts
+import { initBroker } from "@hedwigjs/broker";
+import type { Topic, TopicPayloads } from "{{PACKAGE_NAME}}";
+
+initBroker<Topic, TopicPayloads>({...});
+```
+
+```tsx
+import { getBroker } from "@hedwigjs/broker";
+import { MessageBrokerDevTools } from "@hedwigjs/devtools";
+import { registry } from "{{PACKAGE_NAME}}";
+
+<MessageBrokerDevTools broker={getBroker()} registry={registry} />
+```

package/templates/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+src/index.generated.ts

package/templates/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./domains/*": {
+      "import": "./dist/domains/*.js",
+      "types": "./dist/domains/*.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "node scripts/build.mjs && tsc",
+    "dev": "node scripts/build.mjs --watch & tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

package/templates/scripts/build.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * scripts/build.mjs — codegen реестра топиков.
+ *
+ * Сканирует src/domains/<domain>/<action>.v<N>.ts, валидирует и пишет
+ * src/index.generated.ts.
+ *
+ * Контракт пути:
+ *   src/domains/<domain>/<action>.v<N>.ts
+ *   где <domain> и <action> — kebab-case (^[a-z][a-z0-9-]*$),
+ *   <N> — целое число.
+ *
+ * Топик строится как: <domain>.<action>.v<N>
+ *
+ * Валидация:
+ *   - Глубина вложенности ровно 1 (домен в src/domains/, файл внутри)
+ *   - Имя файла соответствует паттерну
+ *   - Поле name внутри файла совпадает с derived-именем из пути
+ *   - Нет дублей name
+ *
+ * Флаги:
+ *   --watch  — наблюдать за src/domains/, инкрементально пересобирать
+ */
+
+import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync, watch } from "node:fs";
+import { dirname, join } from "node:path";
+
+const ROOT = process.cwd();
+const DOMAINS_DIR = join(ROOT, "src/domains");
+const OUTPUT_FILE = join(ROOT, "src/index.generated.ts");
+
+const DOMAIN_PATTERN = /^[a-z][a-z0-9-]*$/;
+const FILE_NAME_PATTERN = /^([a-z][a-z0-9-]*)\.v(\d+)\.ts$/;
+
+// ────────────────────────────────────────────────────────────────────
+// File discovery
+// ────────────────────────────────────────────────────────────────────
+
+async function listEventFiles() {
+  if (!existsSync(DOMAINS_DIR)) return [];
+
+  const files = [];
+  const domainEntries = await readdir(DOMAINS_DIR, { withFileTypes: true });
+
+  for (const domainEntry of domainEntries) {
+    if (!domainEntry.isDirectory()) continue;
+    if (domainEntry.name.startsWith(".")) continue;
+
+    const domainDir = join(DOMAINS_DIR, domainEntry.name);
+    const fileEntries = await readdir(domainDir, { withFileTypes: true });
+
+    for (const fileEntry of fileEntries) {
+      if (!fileEntry.isFile()) continue;
+      if (!fileEntry.name.endsWith(".ts")) continue;
+      files.push({
+        absolutePath: join(domainDir, fileEntry.name),
+        domain: domainEntry.name,
+        fileName: fileEntry.name,
+      });
+    }
+  }
+
+  return files;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Path → contract derivation
+// ────────────────────────────────────────────────────────────────────
+
+function pascalCase(parts) {
+  return parts
+    .flatMap((p) => p.split(/[-]/))
+    .filter(Boolean)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase())
+    .join("");
+}
+
+function deriveContract(file) {
+  if (!DOMAIN_PATTERN.test(file.domain)) {
+    throw new Error(
+      `Invalid domain '${file.domain}' in src/domains/${file.domain}/${file.fileName}\n` +
+        `  Domain must match ${DOMAIN_PATTERN}`
+    );
+  }
+
+  const match = file.fileName.match(FILE_NAME_PATTERN);
+  if (!match) {
+    throw new Error(
+      `Invalid file name 'src/domains/${file.domain}/${file.fileName}'\n` +
+        `  Expected: <action>.v<N>.ts (kebab-case action, integer version)`
+    );
+  }
+
+  const [, action, version] = match;
+  const topic = `${file.domain}.${action}.v${version}`;
+  const identifier = pascalCase([file.domain, action, `V${version}`]);
+  const importPath = `./domains/${file.domain}/${action}.v${version}`;
+  const topicsKey = topic.replace(/[.\-]/g, "_").toUpperCase();
+
+  return {
+    relPath: `${file.domain}/${file.fileName}`,
+    absolutePath: file.absolutePath,
+    domain: file.domain,
+    action,
+    version,
+    topic,
+    identifier,
+    importPath,
+    topicsKey,
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Validation
+// ────────────────────────────────────────────────────────────────────
+
+async function validateNameMatchesPath(contract) {
+  const content = await readFile(contract.absolutePath, "utf-8");
+  const nameMatch = content.match(/name\s*:\s*["']([^"']+)["']/);
+
+  if (!nameMatch) {
+    throw new Error(
+      `src/domains/${contract.relPath}: cannot find 'name' field.\n` +
+        `  Expected: name: "${contract.topic}",`
+    );
+  }
+
+  const declared = nameMatch[1];
+  if (declared !== contract.topic) {
+    throw new Error(
+      `src/domains/${contract.relPath}: name mismatch.\n` +
+        `  Declared: "${declared}"\n` +
+        `  Expected (from path): "${contract.topic}"`
+    );
+  }
+}
+
+function detectDuplicates(contracts) {
+  const seen = new Map();
+  for (const c of contracts) {
+    const previous = seen.get(c.topic);
+    if (previous) {
+      throw new Error(
+        `Duplicate topic '${c.topic}':\n` +
+          `  - src/domains/${previous.relPath}\n` +
+          `  - src/domains/${c.relPath}`
+      );
+    }
+    seen.set(c.topic, c);
+  }
+}
+
+function detectDuplicateIdentifiers(contracts) {
+  const seen = new Map();
+  for (const c of contracts) {
+    const previous = seen.get(c.identifier);
+    if (previous) {
+      throw new Error(
+        `Duplicate identifier '${c.identifier}' in generated registry:\n` +
+          `  - src/domains/${previous.relPath} → ${previous.topic}\n` +
+          `  - src/domains/${c.relPath} → ${c.topic}\n` +
+          `  Rename one of the actions to disambiguate.`
+      );
+    }
+    seen.set(c.identifier, c);
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Output rendering
+// ────────────────────────────────────────────────────────────────────
+
+const HEADER = `// AUTO-GENERATED. DO NOT EDIT.
+// Run \`npm run build\` to regenerate.
+`;
+
+function renderEmpty() {
+  return `${HEADER}
+export const registry = {} as const;
+export type Topic = keyof typeof registry;
+export type TopicPayloads = {};
+export const TOPICS = {} as const;
+`;
+}
+
+function renderRegistry(contracts) {
+  contracts.sort((a, b) => a.topic.localeCompare(b.topic));
+
+  const imports = contracts
+    .map((c) => `import ${c.identifier} from "${c.importPath}";`)
+    .join("\n");
+
+  const registryEntries = contracts
+    .map((c) => `  "${c.topic}": ${c.identifier},`)
+    .join("\n");
+
+  const topicsEntries = contracts
+    .map((c) => `  ${c.topicsKey}: "${c.topic}",`)
+    .join("\n");
+
+  return `${HEADER}
+${imports}
+
+export const registry = {
+${registryEntries}
+} as const;
+
+export type Topic = keyof typeof registry;
+
+export type TopicPayloads = {
+  [K in Topic]: (typeof registry)[K] extends { payload: infer P } ? P : never;
+};
+
+export const TOPICS = {
+${topicsEntries}
+} as const;
+`;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Main build
+// ────────────────────────────────────────────────────────────────────
+
+async function build() {
+  const files = await listEventFiles();
+  const contracts = files.map(deriveContract);
+
+  for (const c of contracts) {
+    await validateNameMatchesPath(c);
+  }
+
+  detectDuplicates(contracts);
+  detectDuplicateIdentifiers(contracts);
+
+  const output = contracts.length === 0 ? renderEmpty() : renderRegistry(contracts);
+
+  await mkdir(dirname(OUTPUT_FILE), { recursive: true });
+  await writeFile(OUTPUT_FILE, output, "utf-8");
+
+  const count = contracts.length;
+  const noun = count === 1 ? "topic" : "topics";
+  console.log(`✔ Generated src/index.generated.ts (${count} ${noun})`);
+}
+
+async function buildSafe(throwOnError) {
+  try {
+    await build();
+    return true;
+  } catch (err) {
+    console.error(`✗ Build failed:\n  ${err.message}`);
+    if (throwOnError) throw err;
+    return false;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// CLI entry
+// ────────────────────────────────────────────────────────────────────
+
+const watchMode = process.argv.includes("--watch");
+
+if (watchMode) {
+  await buildSafe(false);
+  console.log(`Watching ${DOMAINS_DIR} for changes...`);
+
+  if (!existsSync(DOMAINS_DIR)) {
+    await mkdir(DOMAINS_DIR, { recursive: true });
+  }
+
+  let timer = null;
+  const debouncedRebuild = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      console.log("Change detected, rebuilding...");
+      buildSafe(false);
+    }, 100);
+  };
+
+  watch(DOMAINS_DIR, { recursive: true }, debouncedRebuild);
+} else {
+  const ok = await buildSafe(false);
+  if (!ok) process.exit(1);
+}

package/templates/src/index.generated.ts

@@ -0,0 +1,7 @@
+// AUTO-GENERATED. DO NOT EDIT.
+// Run `npm run build` to regenerate.
+
+export const registry = {} as const;
+export type Topic = keyof typeof registry;
+export type TopicPayloads = {};
+export const TOPICS = {} as const;

package/templates/src/index.ts

@@ -0,0 +1,3 @@
+// Публичный entry org-package'а. Не редактируется.
+// Реэкспортирует всё, что генерит scripts/build.mjs.
+export * from "./index.generated";

package/templates/src/lib/contract.ts

@@ -0,0 +1,36 @@
+/**
+ * Форма контракта одного события.
+ * Используется через `satisfies` в файлах domains/.
+ *
+ * Этот файл копируется initializer'ом в org-package при создании реестра.
+ * После copy редактирование не предполагается.
+ */
+export interface EventContract<
+  TName extends string = string,
+  TPayload = unknown,
+> {
+  /** Имя топика, формат: <domain>.<action>.v<N> */
+  name: TName;
+
+  /** Описание для DevTools и команды */
+  description: string;
+
+  /** Тип payload — объявляется через `as { ... }` */
+  payload: TPayload;
+
+  /** Фикстуры для тестов и DevTools-имитации. Минимум — ключ `happy` */
+  examples: Record<string, TPayload>;
+
+  /** Если событие deprecated — указатель на новую версию */
+  deprecatedBy?: string;
+
+  /**
+   * Отмечает событие как чисто телеметрическое (трейс, TTFB-hint и т.п.):
+   * по замыслу у него может не быть business-подписчиков, и
+   * `NACK NO_SUBSCRIBERS` для него — ожидаемое состояние, а не ошибка.
+   *
+   * DevTools использует этот флаг чтобы рендерить такие NACK'и
+   * нейтрально (не красным) и метить строку бейджем `trace`.
+   */
+  observability?: boolean;
+}

package/templates/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}