@cosmicdrift/kumiko-dev-server 0.328.1 → 0.330.0

package/dist/codegen/render.js

@@ -0,0 +1,273 @@
+// Renders the three generated files under `<appRoot>/.kumiko/`:
+//
+//   1. `types.generated.d.ts` — augments `KumikoEventTypeMap` with every
+//      `r.defineEvent` entry. Pure declarations, no runtime code.
+//
+//   2. `schemas.generated.ts` — re-exports of inline zod schemas, one
+//      per `r.defineEvent("name", z.object({...}))` call that wasn't
+//      already an imported named export. This file is referenced
+//      EXCLUSIVELY via `import type` (in types.generated.d.ts) — the
+//      ts-typescript-strip pass elides it at build time, no runtime
+//      duplication. Only emitted when at least one inline schema exists.
+//
+//   3. `define.ts` — the local `defineWriteHandler` /
+//      `defineQueryHandler` wrappers that pin TMap explicitly. THIS is
+//      where strict mode actually takes effect (see project_x1_typemap_
+//      findings memory): cross-package generic functions with the
+//      default TMap do NOT see the augmentation — only a local wrapper
+//      with an explicit TMap gets it.
+//
+// All three files are written idempotently — same inputs ⇒ same string.
+// The codegen run compares new vs existing content and only writes on
+// actual change, so mtime doesn't tick and the TS language server
+// doesn't reload every 100ms.
+import { basename, relative } from "node:path";
+import { rewriteImportPath } from "./scan-events.js";
+/**
+ * Start-of-block markers for the two handler-derived sections that
+ * `run-codegen.ts` may need to carry forward verbatim from a previous
+ * run (when the current run has no `handlerQns` to render a fresh
+ * block from). Each marker is always the last thing its renderer
+ * emits, so a caller can locate it in a previously-written file and
+ * slice from the marker to EOF to recover the whole block.
+ */
+export const WRITE_HANDLER_QN_MARKER = "// --- WriteHandlerQn (generated from live registry / feature-manifest.json) ---";
+export const TYPED_DISPATCHER_MARKER = "// --- TypedDispatcher (generated from live registry / feature-manifest.json) ---";
+const HEADER = [
+    "// =====================================================================",
+    "// AUTO-GENERATED — DO NOT EDIT BY HAND",
+    "// Regenerated by `bun run build` (kumiko-build) or by the dev-server's",
+    "// file-watcher, which runs codegen on every r.defineEvent change.",
+    "// =====================================================================",
+].join("\n");
+/**
+ * Render `types.generated.d.ts`. Imports the schema-identifiers as
+ * type-only — sources can be either named exports of feature-events
+ * files (kind: "imported") or extracted const-exports of the
+ * co-generated schemas.generated.ts (kind: "inline"). Result is wired
+ * via `z.infer<typeof X>` into the augmentation. Empty events list →
+ * minimal but valid file (still augmentable, just no entries yet —
+ * useful first-time scaffold).
+ */
+export function renderTypesAugmentation(events, outputDirAbs) {
+    // Group identifiers by their resolved (rewritten) module path so each
+    // schema file imports once. Multiple events sharing the same events.ts
+    // file is the common case for the "imported" kind. Inline-events all
+    // share the same module path: "./schemas.generated".
+    const importsByPath = new Map();
+    for (const ev of events) {
+        if (ev.schemaSource.kind === "imported") {
+            const rewritten = rewriteImportPath(ev.schemaSource.schemaModulePath, ev.featureFilePath, outputDirAbs);
+            if (!importsByPath.has(rewritten))
+                importsByPath.set(rewritten, new Set());
+            importsByPath.get(rewritten)?.add(ev.schemaSource.schemaIdentifier);
+        }
+        else {
+            const path = "./schemas.generated";
+            if (!importsByPath.has(path))
+                importsByPath.set(path, new Set());
+            importsByPath.get(path)?.add(ev.schemaSource.generatedConstName);
+        }
+    }
+    const importLines = [];
+    // `z` from zod is needed for `z.infer<typeof X>`; we import it once.
+    importLines.push(`import type { z } from "zod";`);
+    // Stable order — sort module paths alphabetically; identifiers within
+    // a module also alphabetically. Idempotent output.
+    for (const [modPath, idents] of [...importsByPath.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const sortedIdents = [...idents].sort();
+        importLines.push(`import type { ${sortedIdents.join(", ")} } from "${modPath}";`);
+    }
+    const mapEntries = [...events]
+        .sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName))
+        .map((ev) => {
+        const refName = ev.schemaSource.kind === "imported"
+            ? ev.schemaSource.schemaIdentifier
+            : ev.schemaSource.generatedConstName;
+        return `    "${ev.qualifiedName}": z.infer<typeof ${refName}>;`;
+    });
+    // Body block — `declare module` in module-form (because we have an
+    // `export {}` at the end). Module-form makes the augmentation merge
+    // into the target interface; a script-form (`export {}` removed)
+    // would REPLACE the module's exports.
+    const body = [
+        'declare module "@cosmicdrift/kumiko-framework/engine" {',
+        "  interface KumikoEventTypeMap {",
+        ...(mapEntries.length === 0 ? ["    // (no r.defineEvent calls discovered yet)"] : mapEntries),
+        "  }",
+        "}",
+        "",
+        "export {};",
+        "",
+    ].join("\n");
+    return [HEADER, "", ...importLines, "", body].join("\n");
+}
+/**
+ * Render `schemas.generated.ts`. One `export const` per inline-schema
+ * event, named via the qualifiedName-derived stable identifier. The
+ * source-text of the original `z.*(...)` expression is replayed — we
+ * don't try to be cleverer than the zod compiler about reconstructing
+ * the schema. Returns undefined when no inline-schemas exist (so the
+ * runner can skip writing the file entirely).
+ */
+export function renderInlineSchemasFile(events, appRootAbs) {
+    const inlines = events.filter((ev) => ev.schemaSource.kind === "inline");
+    if (inlines.length === 0)
+        return undefined;
+    const lines = [
+        HEADER,
+        "",
+        "// Schema extracts purely for type inference: this file is referenced",
+        "// from types.generated.d.ts via `import type`. ts-strip elides it at",
+        "// build time, so there is NO runtime duplication of the inline schemas",
+        "// in feature files. When an event schema changes: rebuild (`bun run",
+        "// build`) or let the dev-server regenerate it — otherwise the z.infer",
+        "// type drifts from the runtime schema.",
+        "",
+        `import { z } from "zod";`,
+        "",
+    ];
+    // Sort by const-name for stable output.
+    const sorted = [...inlines].sort((a, b) => {
+        const aName = a.schemaSource.kind === "inline" ? a.schemaSource.generatedConstName : "";
+        const bName = b.schemaSource.kind === "inline" ? b.schemaSource.generatedConstName : "";
+        return aName.localeCompare(bName);
+    });
+    for (const ev of sorted) {
+        if (ev.schemaSource.kind !== "inline")
+            continue;
+        const rel = relative(appRootAbs, ev.featureFilePath).split("\\").join("/");
+        // Feature files outside the app root (e.g. a bundled dependency) yield a
+        // `../../..`-walk that clutters the source comment; fall back to the bare
+        // filename. Comment-only — the generated schema is unaffected.
+        const sourcePath = rel.startsWith("..") ? basename(ev.featureFilePath) : rel;
+        lines.push(`// ${ev.qualifiedName} — from ${sourcePath}:${ev.source.line}`, `export const ${ev.schemaSource.generatedConstName} = ${ev.schemaSource.schemaSource};`, "");
+    }
+    return lines.join("\n");
+}
+/**
+ * Render `define.ts` — local thin wrappers that fix TMap to
+ * KumikoEventTypeMap. Apps import `defineWriteHandler` /
+ * `defineQueryHandler` from this file; framework's strict-overload
+ * becomes the only matching overload because TMap is no longer the
+ * eager-resolved default.
+ *
+ * The wrappers are intentionally *thin* — same signature as the
+ * framework's, just with TMap pre-bound. Apps stay portable: switch
+ * the import back to "@cosmicdrift/kumiko-framework/engine" and you're back on the
+ * loose default. Migration is reversible, no behavioural surface change.
+ */
+export function renderDefineFile(handlerQns = []) {
+    const typedDispatcherBlock = handlerQns.length > 0
+        ? [
+            "",
+            TYPED_DISPATCHER_MARKER,
+            `import type { Dispatcher, WriteOpts, WriteResult } from "@cosmicdrift/kumiko-headless";`,
+            `import type { WriteHandlerQn } from "./types.generated";`,
+            "",
+            // Plain `export type { WriteHandlerQn } from "./types.generated"`
+            // only re-exports — with verbatimModuleSyntax it does NOT bind the
+            // name locally, so the `TypedDispatcher` reference below would fail
+            // to resolve. Import above + bare re-export here does both.
+            `export type { WriteHandlerQn };`,
+            "",
+            `/** Dispatcher with write() narrowed to registered handler QNs. */`,
+            `export type TypedDispatcher = Omit<Dispatcher, "write"> & {`,
+            `  write<TData = unknown>(`,
+            `    type: WriteHandlerQn,`,
+            `    payload: unknown,`,
+            `    opts?: WriteOpts,`,
+            `  ): Promise<WriteResult<TData>>;`,
+            `};`,
+            "",
+            `/** Wrap any Dispatcher so write() only accepts registered QNs at compile time. */`,
+            `export function createTypedDispatcher(dispatcher: Dispatcher): TypedDispatcher {`,
+            `  return {`,
+            `    ...dispatcher,`,
+            `    write: (type, payload, opts) => dispatcher.write(type, payload, opts),`,
+            `  };`,
+            `}`,
+            "",
+        ].join("\n")
+        : "";
+    const body = [
+        HEADER,
+        "",
+        "// Triple-slash reference pulls the augmentation into this compile-",
+        "// unit. Belt-and-suspenders against include-glob variations:",
+        "//   - Apps that include `.kumiko/` in tsconfig pick up the .d.ts",
+        "//     transitively; the reference is redundant but harmless.",
+        "//   - Tooling that compiles a narrow file-set (probes, isolated",
+        "//     test programs) typically ignores .d.ts unless explicitly",
+        "//     referenced — without this line, the augmentation is invisible",
+        "//     and `keyof KumikoEventTypeMap` collapses to `never`. Verified",
+        "//     empirically; see strict-mode-diagnostics.test.ts.",
+        '// NOT a `import "./types.generated"` side-effect — the file is .d.ts',
+        "// (declarations only), runtime tools (Vitest, Bun, Node) can't load",
+        "// it. Triple-slash is type-only, fully elided from JS output.",
+        `/// <reference path="./types.generated.d.ts" />`,
+        "",
+        "// Re-export the entire engine surface — apps can switch their imports",
+        "// from `@cosmicdrift/kumiko-framework/engine` to `./.kumiko/define` with a single",
+        "// sed-replace, no fine-grained import-splitting needed. The strict",
+        "// `defineWriteHandler` / `defineQueryHandler` overrides below shadow",
+        "// the loose framework versions in the local module's export table.",
+        `export * from "@cosmicdrift/kumiko-framework/engine";`,
+        "",
+        `import {`,
+        `  defineWriteHandler as fwDefineWriteHandler,`,
+        `  defineQueryHandler as fwDefineQueryHandler,`,
+        `} from "@cosmicdrift/kumiko-framework/engine";`,
+        `import type {`,
+        `  KumikoEventTypeMap,`,
+        `  WriteHandlerDefinition,`,
+        `  WriteHandlerInput,`,
+        `  QueryHandlerDefinition,`,
+        `} from "@cosmicdrift/kumiko-framework/engine";`,
+        `import type { ZodType } from "zod";`,
+        "",
+        `// Strict defineWriteHandler — TMap fixed to the global`,
+        `// KumikoEventTypeMap (which the augmentation extends). ctx.appendEvent`,
+        `// inside the handler resolves K against the FULL augmented map.`,
+        `export function defineWriteHandler<`,
+        `  const TName extends string,`,
+        `  TSchema extends ZodType,`,
+        `  TData = unknown,`,
+        `>(`,
+        `  def: WriteHandlerInput<TName, TSchema, TData, KumikoEventTypeMap>,`,
+        `): WriteHandlerDefinition<TName, TSchema, TData, KumikoEventTypeMap> {`,
+        `  return fwDefineWriteHandler<TName, TSchema, TData, KumikoEventTypeMap>(def);`,
+        `}`,
+        "",
+        `export function defineQueryHandler<`,
+        `  const TName extends string,`,
+        `  TSchema extends ZodType,`,
+        `  TResult = unknown,`,
+        `>(`,
+        `  def: QueryHandlerDefinition<TName, TSchema, TResult, KumikoEventTypeMap>,`,
+        `): QueryHandlerDefinition<TName, TSchema, TResult, KumikoEventTypeMap> {`,
+        `  return fwDefineQueryHandler<TName, TSchema, TResult, KumikoEventTypeMap>(def);`,
+        `}`,
+        typedDispatcherBlock,
+    ].join("\n");
+    return body;
+}
+/**
+ * Render `WriteHandlerQn` type lines — exports a union of all registered
+ * write handler QNs so custom-screen code can type-check dispatcher.write
+ * calls at compile time:
+ *
+ *   ```ts
+ *   import type { WriteHandlerQn } from "@app/define";
+ *   dispatcher.write<WriteHandlerQn>("tenant:write:create", payload);  // ✓
+ *   dispatcher.write<WriteHandlerQn>("tenant:write:creat", payload);   // ✗ TS error
+ *   ```
+ */
+export function renderWriteHandlerTypes(handlerQns) {
+    if (handlerQns.length === 0)
+        return "";
+    // Stable order — callers pass registration order (dev-server) or manifest
+    // order (CLI); bare sort keeps both byte-identical.
+    const lines = [...handlerQns].sort().map((qn) => `  | "${qn}"`);
+    return ["", WRITE_HANDLER_QN_MARKER, `export type WriteHandlerQn =`, ...lines, ";", ""].join("\n");
+}

package/dist/codegen/run-codegen.d.ts

@@ -0,0 +1,20 @@
+import { type ScanWarning } from "./scan-events.js";
+export type CodegenOptions = {
+    /** App-Root — `<appRoot>/.kumiko/` ist der Output-Ordner. */
+    readonly appRoot: string;
+    /** Optional: alle registrierten Write-Handler-QNs. Wenn nicht gesetzt,
+     *  versucht der Codegen `feature-manifest.json` im appRoot zu lesen.
+     *  Die Dev-Server-Integration übergibt die QNs direkt aus der gebooteten
+     *  Registry — CLI ruft sie aus dem Manifest. */
+    readonly handlerQns?: readonly string[];
+};
+export type CodegenResult = {
+    readonly outputDir: string;
+    readonly eventCount: number;
+    readonly warnings: readonly ScanWarning[];
+    readonly didWriteTypes: boolean;
+    readonly didWriteSchemas: boolean;
+    readonly didWriteDefine: boolean;
+    readonly skipped: boolean;
+};
+export declare function runCodegen(opts: CodegenOptions): CodegenResult;

package/dist/codegen/run-codegen.js

@@ -0,0 +1,219 @@
+// runCodegen — top-level entry point. Called by the dev-server (on boot,
+// then on every watched file-change) and by `kumiko-build` (before
+// bundling).
+//
+// Lifecycle:
+//   1. Scan `<appRoot>/src/**` nach r.defineEvent.
+//   2. Render bis zu drei Files unter `<appRoot>/.kumiko/`:
+//        - types.generated.d.ts  (immer wenn Events oder bestehende Datei)
+//        - schemas.generated.ts  (nur wenn ≥1 inline-Schema)
+//        - define.ts             (immer)
+//   3. Schreibe nur bei tatsächlicher Änderung — sonst kein touch
+//      (TS-Sprachserver bleibt cached, Watcher feuert nicht).
+//   4. Wenn 0 Events UND noch kein .kumiko/ existiert: bail. Apps die
+//      `r.defineEvent` nicht nutzen brauchen keinen Wrapper-Pfad und
+//      kein leeres Verzeichnis.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderDefineFile, renderInlineSchemasFile, renderTypesAugmentation, renderWriteHandlerTypes, TYPED_DISPATCHER_MARKER, WRITE_HANDLER_QN_MARKER, } from "./render.js";
+import { scanEvents } from "./scan-events.js";
+export function runCodegen(opts) {
+    const outputDir = join(opts.appRoot, ".kumiko");
+    const outputExists = existsSync(outputDir);
+    const scan = scanEvents({ appRoot: opts.appRoot });
+    const typesPath = join(outputDir, "types.generated.d.ts");
+    const definePath = join(outputDir, "define.ts");
+    const schemasPath = join(outputDir, "schemas.generated.ts");
+    const packageJsonPath = join(outputDir, "package.json");
+    // Skip-Pfad: keine Events gefunden + keine bestehende Output-Dir
+    // bedeutet die App nutzt r.defineEvent nicht (oder noch nicht). Kein
+    // leeres `.kumiko/` zurücklassen — das hilft niemandem und produziert
+    // false-positives in CI ("eh, was ist denn das hier"). Wenn die Dir
+    // schon existiert (alter Run), generieren wir trotzdem — ein Refactor
+    // der den letzten r.defineEvent löscht soll das Output dann auch
+    // bereinigen, statt eine stale Augmentation liegen zu lassen.
+    if (scan.events.length === 0 && !outputExists) {
+        return {
+            outputDir,
+            eventCount: 0,
+            warnings: scan.warnings,
+            didWriteTypes: false,
+            didWriteSchemas: false,
+            didWriteDefine: false,
+            skipped: true,
+        };
+    }
+    mkdirSync(outputDir, { recursive: true });
+    const typesContent = renderTypesAugmentation(scan.events, outputDir);
+    // `opts.handlerQns` undefined means the caller (kumiko-build) has no
+    // live feature registry to draw from and relies on the manifest
+    // fallback. That fallback can't tell "no handlers exist" apart from
+    // "the manifest doesn't exist" — both come back as an empty array —
+    // so an empty result here is a known-lossy read, not authoritative
+    // data the way run-dev-app's live registry is.
+    const usingManifestFallback = opts.handlerQns === undefined;
+    const handlerQns = opts.handlerQns ?? readHandlerQnsFromManifest(opts.appRoot);
+    const hasHandlerQns = handlerQns.length > 0;
+    const defineContent = renderDefineFile(handlerQns);
+    const schemasContent = renderInlineSchemasFile(scan.events, opts.appRoot);
+    // package.json — turns `.kumiko/` into a real installable package
+    // named `@app/define`. Apps that declare
+    //   "@app/define": "link:./.kumiko"
+    // in their package.json get a node_modules symlink that the runtime
+    // (Node, Vitest, Bun) all resolve via standard module-lookup. Yarn 4
+    // is required — yarn classic v1 ignored deps in versionless workspaces.
+    const packageJsonContent = renderKumikoPackageJson();
+    // WriteHandlerQn-Union an den types-Content anhängen (optional). Der
+    // Dev-Server übergibt handlerQns aus der lebenden Registry (genauer);
+    // der CLI-Fallback liest das feature-manifest.json falls vorhanden.
+    //
+    // Preserve only applies to the manifest-fallback path: a caller that
+    // explicitly passes `handlerQns: []` (the dev-server, when an app
+    // truly registers zero write handlers) means it — that's real data,
+    // not a missing-manifest gap, so it clears the block like before.
+    // Only the manifest fallback coming back empty is ambiguous enough to
+    // warrant carrying the previous block forward instead of dropping it.
+    const shouldPreserveStaleBlock = !hasHandlerQns && usingManifestFallback;
+    const finalTypesContent = shouldPreserveStaleBlock
+        ? withPreservedBlock(typesContent, typesPath, WRITE_HANDLER_QN_MARKER, LEGACY_WRITE_HANDLER_QN_ANCHOR)
+        : `${typesContent}${renderWriteHandlerTypes(handlerQns)}`;
+    const finalDefineContent = shouldPreserveStaleBlock
+        ? withPreservedBlock(defineContent, definePath, TYPED_DISPATCHER_MARKER, LEGACY_TYPED_DISPATCHER_ANCHOR)
+        : defineContent;
+    const didWriteTypes = writeIfChanged(typesPath, finalTypesContent);
+    const didWriteDefine = writeIfChanged(definePath, finalDefineContent);
+    writeIfChanged(packageJsonPath, packageJsonContent);
+    const didWriteSchemas = schemasContent !== undefined
+        ? writeIfChanged(schemasPath, schemasContent)
+        : removeIfExists(schemasPath);
+    const warnings = shouldPreserveStaleBlock
+        ? [
+            ...scan.warnings,
+            {
+                message: "No feature-manifest.json found — the WriteHandlerQn/TypedDispatcher block could not be determined from here; run the dev-server to get the exact handler list.",
+            },
+        ]
+        : scan.warnings;
+    return {
+        outputDir,
+        eventCount: scan.events.length,
+        warnings,
+        didWriteTypes,
+        didWriteSchemas,
+        didWriteDefine,
+        skipped: false,
+    };
+}
+/**
+ * Static package.json content — turns `.kumiko/` into an installable
+ * package called `@app/define`. The shape never depends on event-scans,
+ * so we don't bother passing the events in.
+ *
+ * Two things to keep stable:
+ *   - `name: "@app/define"` matches what handler imports use.
+ *   - `exports."."` points at the wrapper, `exports."./*"` lets apps
+ *     reach into types.generated etc. via `@app/types.generated`.
+ */
+function renderKumikoPackageJson() {
+    const pkg = {
+        name: "@app/define",
+        private: true,
+        // license: keep the generated package out of unknown-license territory
+        // for the License-Check guard. The repo is BUSL-1.1-licensed, the generated
+        // wrapper inherits that — the file just re-exports framework code,
+        // there's no original IP in `.kumiko/` worth a different license.
+        license: "BUSL-1.1",
+        version: "0.0.0",
+        type: "module",
+        main: "./define.ts",
+        types: "./define.ts",
+        exports: {
+            ".": "./define.ts",
+            "./*": "./*",
+        },
+    };
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+/**
+ * Idempotent write — only touches the file when its content actually
+ * changed. Critical for the dev-server watcher: a no-op codegen pass
+ * must NOT trigger a full TS-language-server rebuild (which would
+ * happen on every mtime change).
+ */
+function writeIfChanged(path, content) {
+    const existing = readExistingOrUndefined(path);
+    if (existing === content)
+        return false;
+    writeFileSync(path, content, "utf-8");
+    return true;
+}
+function readExistingOrUndefined(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+// Pre-marker renderer output has no WRITE_HANDLER_QN_MARKER/TYPED_DISPATCHER_MARKER
+// line to find — a file generated before this fix still needs to round-trip.
+// Each anchor is the first line of its block under the old renderer, so slicing
+// from the preceding newline recovers the same block the marker path recovers.
+const LEGACY_WRITE_HANDLER_QN_ANCHOR = `export type WriteHandlerQn =`;
+const LEGACY_TYPED_DISPATCHER_ANCHOR = `import type { Dispatcher, WriteOpts, WriteResult } from "@cosmicdrift/kumiko-headless";`;
+/**
+ * Appends whichever handler-derived block a previous run left behind
+ * in `existingPath`, found via its start-of-block `marker` (or, for a
+ * file generated before markers existed, `legacyAnchor`). Used when
+ * the current run has no `handlerQns` of its own — the block can't be
+ * re-derived, so the only options are "delete it" (the #2757 bug) or
+ * "leave it exactly as it was". The marker is always emitted as the
+ * last thing its renderer produces, so slicing from it to EOF recovers
+ * the whole block regardless of how many times this preserve-path runs
+ * in a row.
+ */
+function withPreservedBlock(freshContent, existingPath, marker, legacyAnchor) {
+    const existing = readExistingOrUndefined(existingPath);
+    const preserved = extractBlock(existing, marker) ?? extractBlock(existing, legacyAnchor);
+    return preserved !== undefined ? `${freshContent}${preserved}` : freshContent;
+}
+function extractBlock(content, anchor) {
+    if (content === undefined)
+        return undefined;
+    const idx = content.indexOf(`\n${anchor}`);
+    return idx === -1 ? undefined : content.slice(idx);
+}
+/**
+ * Remove a previously-generated file when the latest scan no longer
+ * produces it (e.g. the last inline-schema was refactored to a named
+ * export). Returns true when an actual unlink happened.
+ */
+function removeIfExists(path) {
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}
+/**
+ * Fallback: liest `feature-manifest.json` aus dem appRoot und extrahiert
+ * alle Write-Handler-QNs. Fehlende/stale Manifeste sind kein Fehler —
+ * dann wird schlicht keine `WriteHandlerQn`-Union generiert (CLI ohne
+ * Manifest oder CI-Setup ohne Manifest-Generator).
+ */
+function readHandlerQnsFromManifest(appRoot) {
+    try {
+        const manifestPath = join(appRoot, "feature-manifest.json");
+        const raw = readFileSync(manifestPath, "utf-8");
+        const manifest = JSON.parse(raw);
+        const qns = [];
+        for (const f of manifest.features) {
+            if (f.writeHandlers)
+                qns.push(...f.writeHandlers);
+        }
+        qns.sort();
+        return qns;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/codegen/scan-events.d.ts

@@ -0,0 +1,76 @@
+export type ScannedEvent = {
+    /** Qualified event-name as it appears in the events table:
+     *  `<feature>:event:<inner>`. The KumikoEventTypeMap key. */
+    readonly qualifiedName: string;
+    /** Where the type for this event's payload comes from. Two flavours:
+     *
+     *    { kind: "imported", schemaIdentifier, schemaModulePath }
+     *      Schema is a named export of another file. Augmentation
+     *      `import type`-s it from there.
+     *
+     *    { kind: "inline", schemaSource, generatedConstName }
+     *      Schema was inlined at the call-site. We extract the source
+     *      text into `schemas.generated.ts` under `generatedConstName`
+     *      and import-type from there. */
+    readonly schemaSource: SchemaSource;
+    /** Absolute disk-path of the feature file (for relative-path
+     *  resolution + diagnostics). */
+    readonly featureFilePath: string;
+    /** For diagnostics + dedup logging. */
+    readonly source: {
+        readonly file: string;
+        readonly line: number;
+    };
+};
+export type SchemaSource = {
+    readonly kind: "imported";
+    readonly schemaIdentifier: string;
+    readonly schemaModulePath: string;
+} | {
+    readonly kind: "inline";
+    /** zod source text — `z.object({ id: z.string() })` etc. */
+    readonly schemaSource: string;
+    /** Name we'll generate inside `schemas.generated.ts`. Stable
+     *  + qualified-name-derived so reorder of features doesn't
+     *  rename them. */
+    readonly generatedConstName: string;
+};
+export type ScanWarning = {
+    /** Absent for warnings that aren't tied to a scanned source line
+     *  (e.g. a codegen-level warning about a missing manifest file). */
+    readonly file?: string;
+    readonly line?: number;
+    readonly message: string;
+};
+export type ScanResult = {
+    readonly events: readonly ScannedEvent[];
+    readonly warnings: readonly ScanWarning[];
+};
+/** Renders a `ScanWarning` for terminal output; omits the location prefix when the warning has no source line. */
+export declare function formatScanWarning(warning: ScanWarning): string;
+export type ScanOptions = {
+    /** App-Wurzel — alles unter `<root>/src` wird gescannt. Tests +
+     *  generated-files (`.kumiko`, `dist*`, `node_modules`) sind raus. */
+    readonly appRoot: string;
+};
+/**
+ * Scant `appRoot/src/**` nach `r.defineEvent(...)`-Aufrufen und liefert
+ * eine deduplizierte Liste aus ScannedEvent. Doppelte qualifiedName
+ * landen mit einer Warnung in der Result — Codegen schreibt nur den
+ * ERSTEN, sodass das generated File compile-stabil bleibt.
+ */
+export declare function scanEvents(opts: ScanOptions): ScanResult;
+/**
+ * Stable identifier-safe rewrite of a qualifiedName like
+ * `pubsubOrders:event:order-placed` → `_kg_pubsubOrders__orderPlaced`.
+ * Used for the `export const` name in `schemas.generated.ts`. Same
+ * transform in scan + render keeps the two sides in sync.
+ */
+export declare function qualifiedNameToConstName(qualifiedName: string): string;
+/**
+ * Resolves the relative schema-import path from the feature-file's
+ * point-of-view to a path relative to `.kumiko/` (which is where the
+ * generated d.ts file lives). Workspace-package specifiers
+ * (`@cosmicdrift/kumiko-...`) are returned as-is.
+ */
+export declare function rewriteImportPath(schemaModulePath: string, featureFilePath: string, outputDirAbs: string): string;