@cosmicdrift/kumiko-dev-server 0.1.0

package/src/drizzle-config.ts

@@ -0,0 +1,44 @@
+// kumikoDrizzleConfig — Convention-Helper für drizzle.config.ts in App-
+// Workspaces. Convention-driven Defaults statt Boilerplate-Copy:
+//
+//   import { kumikoDrizzleConfig } from "@cosmicdrift/kumiko-dev-server/drizzle-config";
+//   export default kumikoDrizzleConfig();
+//
+// Default-Pfade:
+//   schema:  "./drizzle/schema.ts"
+//   out:     "./drizzle/migrations"
+//   db url:  process.env[DATABASE_URL] (override via options)
+//   dialect: "postgresql"
+//   verbose + strict: true (drizzle-kit-Defaults für Production-Workflow)
+//
+// Apps mit untypischer Verzeichnis-Struktur können einzelne Werte
+// überschreiben, der Rest bleibt Convention.
+
+import { defineConfig } from "drizzle-kit";
+
+export type KumikoDrizzleConfigOptions = {
+  /** Pfad zum Schema-Barrel relativ zum App-Root. Default: "./drizzle/schema.ts". */
+  readonly schemaPath?: string;
+  /** Migrations-Out-Folder relativ zum App-Root. Default: "./drizzle/migrations". */
+  readonly outDir?: string;
+  /** Env-Var-Name für die Database-URL. Default: "DATABASE_URL". */
+  readonly databaseUrlEnv?: string;
+  /** Fallback-URL wenn die Env-Var leer ist (für lokale Dev-Setups).
+   *  Default: postgres://kumiko:kumiko@localhost:15432/kumiko_dev (kumiko dev-stack). */
+  readonly fallbackDatabaseUrl?: string;
+};
+
+export function kumikoDrizzleConfig(options: KumikoDrizzleConfigOptions = {}) {
+  const envName = options.databaseUrlEnv ?? "DATABASE_URL";
+  const fallback =
+    options.fallbackDatabaseUrl ?? "postgres://kumiko:kumiko@localhost:15432/kumiko_dev";
+  const url = process.env[envName] ?? fallback;
+  return defineConfig({
+    schema: options.schemaPath ?? "./drizzle/schema.ts",
+    out: options.outDir ?? "./drizzle/migrations",
+    dialect: "postgresql",
+    dbCredentials: { url },
+    verbose: true,
+    strict: true,
+  });
+}

package/src/drizzle-tables-auth-mode.ts

@@ -0,0 +1,32 @@
+// Drizzle-Schema-Barrel: Framework-Infrastruktur-Tables.
+//
+// Re-exportiert die Framework-eigenen Tables (Event-Store + Pipeline-State)
+// die jede App in der DB haben muss. App-Author schreibt:
+//
+//   // drizzle/schema.ts
+//   export * from "@cosmicdrift/kumiko-dev-server/drizzle-tables-auth-mode";
+//   export * from "./schema.generated";   // App-eigene + Bundle-Entity-Tables
+//
+// drizzle-kit sucht im schema-Module nur nach pgTable-Instances und
+// ignoriert alle anderen exports — `export *` ist hier sicher.
+//
+// Bundle-Entity-Tables (configValuesTable, tenantTable, userTable,
+// userSessionTable, tenantMembershipsTable etc.) sind bewusst NICHT hier:
+// sie kommen über schema.generated.ts via buildDrizzleTable aus den
+// r.entity()-Definitionen, das ist seit der entity.indexes-API die
+// Single-Source-of-Truth. Doppelte Re-Exports würden zwei pgTable-
+// Instances mit identischem Index-Namen erzeugen — drizzle-kit warnt.
+//
+// (Datei-Name "auth-mode" ist historisch — heute ist der Inhalt reine
+// Framework-Infra. Umbenennen ist breaking change für App-Imports.)
+
+// Framework-Infra (immer da, unabhängig von Features)
+export {
+  archivedStreamsTable,
+  eventsTable,
+  snapshotsTable,
+} from "@cosmicdrift/kumiko-framework/event-store";
+export {
+  eventConsumerStateTable,
+  projectionStateTable,
+} from "@cosmicdrift/kumiko-framework/pipeline";

package/src/drizzle-tables-minimal.ts

@@ -0,0 +1,22 @@
+// Drizzle-Schema-Barrel: Minimal (nur Framework-Infra, kein Auth).
+//
+// Apps OHNE Auth-Stack (anonymous-only, embedded Demos, Headless-APIs)
+// brauchen nur die Framework-Infrastructure-Tables — Event-Store +
+// Pipeline-State. Verwendung in drizzle/schema.ts:
+//
+//   export * from "@cosmicdrift/kumiko-dev-server/drizzle-tables-minimal";
+//   export * from "./schema.generated";   // App-eigene Entity-Tables
+//
+// Wer Auth-Tables will, nutzt drizzle-tables-auth-mode (umfasst Minimal
+// plus Bundle-Tables für Config, Tenant, User, Sessions).
+
+export {
+  archivedStreamsTable,
+  eventsTable,
+  snapshotsTable,
+  upcasterDeadLetterTable,
+} from "@cosmicdrift/kumiko-framework/event-store";
+export {
+  eventConsumerStateTable,
+  projectionStateTable,
+} from "@cosmicdrift/kumiko-framework/pipeline";

package/src/few-shot-corpus.ts

@@ -0,0 +1,369 @@
+// buildFewShotCorpus — extracts feature-files from the repo into a
+// structured JSON corpus that L2 (Prompt-Pipeline) feeds into the LLM
+// at generation time. One entry per feature-file, four data sources
+// per entry: raw source text, package.json description, parsed
+// FeaturePattern[], plus pattern-categories from the C4 library.
+//
+// **Why a checked-in JSON file (docs/few-shot-corpus.json):**
+//   - Offline-consumable: AI-Builder can prompt without re-parsing
+//     30+ feature files at request time.
+//   - Diff-reviewable: when a feature changes, the corpus diff shows
+//     up in the PR — humans see how the example surface shifted.
+//   - Portable: the corpus is a flat JSON, can ship to a hosted LLM
+//     service / fine-tuning pipeline / customer environment without
+//     dragging the framework's parser along.
+//
+// **Authoring-Style classification:**
+//   - `canonical` → 0 ParseErrors. The example is "do it like this"
+//     for the LLM.
+//   - `legacy` → has ParseErrors. The example shows what code looks
+//     like in the wild (Factory-style, identifier-refs) and is useful
+//     for understanding intent — but the LLM should NOT replicate
+//     this style. L2 marks legacy entries as "do not generate".
+//
+// **Why the corpus includes legacy entries but the Designer does not:**
+//   The two consumers want different slices of the same data. L2 needs
+//   counter-examples (showing the LLM what *not* to emit raises the
+//   chance of clean output), so legacy entries are kept and tagged.
+//   The Designer can only round-trip canonical-form patterns through
+//   the AST-Patcher — legacy entries would render as read-only with
+//   no edit affordance, which is worse than hiding them. So the corpus
+//   builder is permissive, and the Designer filters at read-time.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  type FeaturePattern,
+  type FeaturePatternKind,
+  PATTERN_LIBRARY,
+  type ParseError,
+  parseFeatureFile,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// =============================================================================
+// Public types
+// =============================================================================
+
+export type AuthoringStyle = "canonical" | "legacy";
+
+export type CorpusWarning = {
+  /** Repo-relative path to the file that triggered the warning. */
+  readonly sourcePath: string;
+  /** Human-readable explanation. Currently only "parser-throw" but
+   *  kept open-ended so future builders can add more (e.g.
+   *  "duplicate-id", "no-feature-name"). */
+  readonly reason: string;
+};
+
+export type FewShotEntry = {
+  /** Stable id derived from the path (`samples/recipes/basic-entity`). */
+  readonly id: string;
+  /** Repo-relative path to the feature-file. */
+  readonly sourcePath: string;
+  /** Repo-relative path to the workspace package.json (for description lookup). */
+  readonly packageJsonPath: string | undefined;
+  /** Workspace name (`@cosmicdrift/kumiko-sample-basic-entity`). */
+  readonly packageName: string | undefined;
+  /** English description from package.json. */
+  readonly description: string | undefined;
+  /** Feature name from `defineFeature("...", ...)`. Undefined if the
+   *  parser couldn't read it (rare — implies a non-feature file got
+   *  picked up). */
+  readonly featureName: string | undefined;
+  /** Pattern-categories present in this feature, deduplicated. Useful
+   *  as topic-tags for retrieval ("show me cross-cutting examples"). */
+  readonly tags: readonly string[];
+  /** Counts per pattern-kind — quick stats without scanning the
+   *  patterns array. */
+  readonly patternsByKind: Readonly<Record<string, number>>;
+  /** All parsed patterns. Same shape the parser emits. */
+  readonly patterns: readonly FeaturePattern[];
+  /** Errors the parser raised. Empty for canonical-form features. */
+  readonly parseErrors: readonly ParseError[];
+  /** `canonical` (clean parse) or `legacy` (parser couldn't read it
+   *  fully — Factory-style / identifier-refs). */
+  readonly authoringStyle: AuthoringStyle;
+  /** Raw source text — kept verbatim so the LLM can train on the
+   *  exact byte-form, including comments + whitespace. */
+  readonly rawSource: string;
+};
+
+export type FewShotCorpus = {
+  /** ISO-instant when the corpus was generated. */
+  readonly generatedAt: string;
+  /** Total entry count, broken down by authoringStyle for quick stats. */
+  readonly totals: {
+    readonly all: number;
+    readonly canonical: number;
+    readonly legacy: number;
+  };
+  readonly entries: readonly FewShotEntry[];
+  /** Files that were discovered but couldn't be turned into entries.
+   *  Surfaces parser crashes + duplicate-id collisions instead of
+   *  swallowing them — the regenerate-script reports these to the user
+   *  and the drift-test asserts the count stays constant. */
+  readonly warnings: readonly CorpusWarning[];
+};
+
+export type BuildFewShotCorpusOptions = {
+  /** Repo root — used for relative-path output and security guards. */
+  readonly repoRoot: string;
+  /** Folders to scan recursively. Defaults to samples/* + bundled-features. */
+  readonly scanRoots?: readonly string[];
+};
+
+// =============================================================================
+// Builder
+// =============================================================================
+
+const FEATURE_FILE_PATTERN = /(?:^|\/)(feature|.*\.feature)\.ts$/;
+
+const DEFAULT_SCAN_ROOTS: readonly string[] = [
+  "samples/recipes",
+  "samples/apps",
+  "samples/showcases",
+  "packages/bundled-features/src",
+];
+
+// Static timestamp keeps the JSON output deterministic across CI runs —
+// the regenerate-script could overwrite this with a real timestamp,
+// but drift-tests compare structural data, not timestamps. Centralized
+// here so the build path and any future inspector use the same value.
+const STATIC_GENERATED_AT = "1970-01-01T00:00:00Z";
+
+export function buildFewShotCorpus(options: BuildFewShotCorpusOptions): FewShotCorpus {
+  const repoRoot = resolve(options.repoRoot);
+  const scanRoots = (options.scanRoots ?? DEFAULT_SCAN_ROOTS).map((r) => resolve(repoRoot, r));
+
+  const featureFiles: string[] = [];
+  for (const root of scanRoots) {
+    if (!existsSync(root)) continue;
+    walkDir(root, featureFiles);
+  }
+  featureFiles.sort();
+
+  const entries: FewShotEntry[] = [];
+  const warnings: CorpusWarning[] = [];
+  const seenIds = new Map<string, string>();
+
+  for (const filePath of featureFiles) {
+    const result = buildEntry(filePath, repoRoot);
+    if (result.warning) {
+      warnings.push(result.warning);
+      continue;
+    }
+    const entry = result.entry;
+    const previousPath = seenIds.get(entry.id);
+    if (previousPath) {
+      // Two feature-files mapped to the same id. The corpus uses ids
+      // for retrieval — duplicates would silently overwrite each other
+      // in any consumer that built a Map<id, entry>. Surface as a
+      // warning, drop the second occurrence.
+      warnings.push({
+        sourcePath: entry.sourcePath,
+        reason: `duplicate-id: collides with ${previousPath}`,
+      });
+      continue;
+    }
+    seenIds.set(entry.id, entry.sourcePath);
+    entries.push(entry);
+  }
+
+  const canonical = entries.filter((e) => e.authoringStyle === "canonical").length;
+  return {
+    generatedAt: STATIC_GENERATED_AT,
+    totals: {
+      all: entries.length,
+      canonical,
+      legacy: entries.length - canonical,
+    },
+    entries,
+    warnings,
+  };
+}
+
+type BuildEntryResult =
+  | { readonly entry: FewShotEntry; readonly warning?: never }
+  | { readonly entry?: never; readonly warning: CorpusWarning };
+
+function buildEntry(filePath: string, repoRoot: string): BuildEntryResult {
+  const sourcePath = relative(repoRoot, filePath);
+
+  let parsed: ReturnType<typeof parseFeatureFile>;
+  try {
+    parsed = parseFeatureFile(filePath);
+  } catch (err) {
+    // ts-morph couldn't read the file (syntax-error, IO problem, weird
+    // encoding). Skip the entry but record *why* — silent skip used to
+    // hide newly broken feature-files until L2 hit them.
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+      warning: { sourcePath, reason: `parser-throw: ${detail}` },
+    };
+  }
+
+  const rawSource = readFileSync(filePath, "utf8");
+  const id = pathToId(sourcePath);
+
+  const pkgInfo = findPackageJson(filePath, repoRoot);
+
+  const tags = collectTags(parsed.patterns);
+  const patternsByKind = countPatternsByKind(parsed.patterns);
+
+  const authoringStyle: AuthoringStyle = parsed.errors.length === 0 ? "canonical" : "legacy";
+
+  // SourceLocation.file is an absolute path coming out of the parser —
+  // strip it to repo-relative so the corpus diff stays stable across
+  // machines / CI runners. Same for ParseError.source.file.
+  const patterns = parsed.patterns.map((p) => relativizeSources(p, repoRoot) as FeaturePattern);
+  const parseErrors = parsed.errors.map((e) => ({
+    ...e,
+    source: { ...e.source, file: relative(repoRoot, e.source.file) },
+  }));
+
+  return {
+    entry: {
+      id,
+      sourcePath,
+      packageJsonPath: pkgInfo?.relPath,
+      packageName: pkgInfo?.name,
+      description: pkgInfo?.description,
+      featureName: parsed.featureName,
+      tags,
+      patternsByKind,
+      patterns,
+      parseErrors,
+      authoringStyle,
+      rawSource,
+    },
+  };
+}
+
+/**
+ * Recursively walk a value and rewrite every nested SourceLocation's
+ * `file` field to be repo-relative. Identifies SourceLocation by
+ * structural shape (`{ file, start, end, raw }`) rather than by
+ * type-tag — the parsed objects are plain JSON-ish at this point and
+ * a discriminator would complicate the renderer.
+ *
+ * Typed `unknown → unknown` so the walker stays honest about what it
+ * sees. The single boundary cast lives at the call site
+ * (`as FeaturePattern`) where the input contract is known.
+ */
+function relativizeSources(value: unknown, repoRoot: string): unknown {
+  if (Array.isArray(value)) {
+    return value.map((v) => relativizeSources(v, repoRoot));
+  }
+  if (value && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    if (
+      typeof obj["file"] === "string" &&
+      typeof obj["raw"] === "string" &&
+      typeof obj["start"] === "object" &&
+      typeof obj["end"] === "object"
+    ) {
+      return { ...obj, file: relative(repoRoot, obj["file"]) };
+    }
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = relativizeSources(v, repoRoot);
+    }
+    return out;
+  }
+  return value;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Stable id from the source path. Drops the leading `samples/` or
+ * `packages/` prefix and the trailing `/src/feature.ts` suffix so the
+ * id reads like the canonical short name (`basic-entity`,
+ * `bundled-features/auth-email-password`).
+ */
+export function pathToId(sourcePath: string): string {
+  return sourcePath
+    .replace(/^(samples|packages)\//, "")
+    .replace(/\/src\/feature\.ts$/, "")
+    .replace(/\/feature\.ts$/, "");
+}
+
+function walkDir(dir: string, acc: string[]): void {
+  let entries: { name: string; isDirectory: () => boolean; isFile: () => boolean }[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const name = String(entry.name);
+    const full = join(dir, name);
+    if (entry.isDirectory()) {
+      if (name === "node_modules" || name === "dist" || name === "dist-server") continue;
+      if (name.startsWith(".")) continue;
+      walkDir(full, acc);
+    } else if (entry.isFile() && FEATURE_FILE_PATTERN.test(full)) {
+      acc.push(full);
+    }
+  }
+}
+
+/**
+ * Walk upward from `featureFile` to find the nearest `package.json` and
+ * pluck name + description out of it. Stops at `repoRoot`.
+ */
+function findPackageJson(
+  featureFile: string,
+  repoRoot: string,
+): { relPath: string; name: string | undefined; description: string | undefined } | undefined {
+  let dir = dirname(featureFile);
+  const stopAt = resolve(repoRoot);
+  while (true) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, "utf8")) as {
+          name?: unknown;
+          description?: unknown;
+        };
+        return {
+          relPath: relative(repoRoot, candidate),
+          name: typeof pkg.name === "string" ? pkg.name : undefined,
+          description: typeof pkg.description === "string" ? pkg.description : undefined,
+        };
+      } catch {
+        // Malformed package.json — keep walking up.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir || dir === stopAt) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * Collect the union of pattern-categories present in the feature.
+ * Categories come from the pattern-library — the same vocabulary the
+ * Designer / AI-Builder uses for filtering ("show me background-jobs
+ * examples").
+ */
+function collectTags(patterns: readonly FeaturePattern[]): readonly string[] {
+  const tags = new Set<string>();
+  for (const p of patterns) {
+    const schema = PATTERN_LIBRARY[p.kind as FeaturePatternKind];
+    if (schema) tags.add(schema.category);
+  }
+  return [...tags].sort();
+}
+
+function countPatternsByKind(
+  patterns: readonly FeaturePattern[],
+): Readonly<Record<string, number>> {
+  const counts: Record<string, number> = {};
+  for (const p of patterns) {
+    counts[p.kind] = (counts[p.kind] ?? 0) + 1;
+  }
+  return counts;
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// Public API für den Kumiko-Dev-Server. Zwei Schichten:
+//
+//   - createKumikoServer (low-level)
+//     Bun.serve-Wrapper der Client-Bundle, /styles.css, AppSchema-
+//     Injection, SSE-Reload und einen Auto-Mint-JWT-Modus liefert. Nimmt
+//     features + clientEntry direkt an, kein Auth-Auto-Wiring. Wer
+//     einen ungewöhnlichen Auth-Setup braucht (alternative Membership-
+//     Query, eigener Rate-Limiter, custom Login-Routes) geht hier rein.
+//
+//   - runDevApp (high-level)
+//     Mischt die Standard-Features (config/user/tenant/auth-email-
+//     password) automatisch dazu wenn `auth` gesetzt ist, wired die
+//     Login-Routes + Error-Map, ruft seedAdmin im onAfterSetup. Default
+//     für Sample-Apps und Showcases — 5-10 Zeilen Bootstrap statt 50.
+
+// Build-Toolchain (buildProdBundle, Bun.build, Tailwind-Pipeline, ts-morph) lebt
+// im Sub-Path-Export `@cosmicdrift/kumiko-dev-server/build`. Damit zieht der Main-Barrel
+// kein Bun-Toolchain-Bundle mehr in Production-Reads (z.B. wenn drizzle-kit
+// die App-Config unter Node lädt).
+export {
+  type CodegenOptions,
+  type CodegenResult,
+  runCodegen,
+  type ScannedEvent,
+  type ScanWarning,
+  scanEvents,
+} from "./codegen";
+export { type ComposeFeaturesOptions, composeFeatures } from "./compose-features";
+export {
+  type CreateKumikoServerOptions,
+  createKumikoServer,
+  type KumikoServerHandle,
+  resolveStylesheet,
+} from "./create-kumiko-server";
+export type {
+  AuthoringStyle,
+  BuildFewShotCorpusOptions,
+  CorpusWarning,
+  FewShotCorpus,
+  FewShotEntry,
+} from "./few-shot-corpus";
+export { buildFewShotCorpus, pathToId } from "./few-shot-corpus";
+export type { RunDevAppAuthOptions, RunDevAppOptions, SeedFn } from "./run-dev-app";
+export { runDevApp } from "./run-dev-app";
+export type {
+  EmailVerificationSetup,
+  InviteSetup,
+  PasswordResetSetup,
+  ProdAppHandle,
+  ProdSeedFn,
+  RunProdAppAuthOptions,
+  RunProdAppOptions,
+  SignupSetup,
+} from "./run-prod-app";
+export { runProdApp } from "./run-prod-app";
+export type { ScaffoldFeatureOptions, ScaffoldFeatureResult } from "./scaffold-feature";
+export { scaffoldFeature } from "./scaffold-feature";

package/src/inject-schema.ts

@@ -0,0 +1,24 @@
+// Injiziert das Server-aufgelöste AppSchema in das HTML-Template damit
+// createKumikoApp() es synchron unter `window.__KUMIKO_SCHEMA__` vorfindet.
+// JSON ist valides JS — direkt eingebettet, der Browser parsed das
+// Object-Literal nativ.
+//
+// Geteilt zwischen dev-server (Schema kommt frisch aus dem laufenden
+// Prozess) und prod-server (Schema wird beim Boot einmal berechnet und
+// in die statisch ausgelieferte index.html injiziert). Beide Pfade
+// nutzen dieselbe Tag-Form damit `createKumikoApp` den Lookup nicht je
+// nach Kontext anders machen muss.
+//
+// Idempotenz: wenn das HTML schon einen __KUMIKO_SCHEMA__-Marker hat,
+// wird nicht doppelt injected — verhindert dass repeated index.html-
+// Reads (prod) oder bereits-vorbereitete templates (custom CI-builds)
+// stacking-Tags produzieren.
+
+export function injectSchema(html: string, schemaJson: string): string {
+  if (html.includes("__KUMIKO_SCHEMA__")) return html;
+  const tag = `<script>window.__KUMIKO_SCHEMA__=${schemaJson};</script>`;
+  if (html.includes('<script src="/client.js"')) {
+    return html.replace('<script src="/client.js"', `${tag}<script src="/client.js"`);
+  }
+  return html.includes("</body>") ? html.replace("</body>", `${tag}</body>`) : html + tag;
+}

package/src/resolve-tailwind-cli.ts

@@ -0,0 +1,28 @@
+// Resolved den lokal installierten @tailwindcss/cli-Bin auf seinen
+// absoluten Dateipfad. Wir vermeiden `bunx`, weil das auch bei lokal
+// installiertem Package noch das Registry-Manifest fragt und ohne Netz
+// mit `FailedToOpenSocket` stirbt.
+//
+// Ausgelagert aus create-kumiko-server.ts, damit unter vitest/Node
+// testbar (Bun-Branch + Resolve-Fail-Branch) ohne den Server zu
+// booten.
+
+import { resolve } from "node:path";
+
+type BunResolver = { resolveSync: (id: string, from: string) => string };
+
+export type ResolveTailwindCliDeps = {
+  readonly bun?: BunResolver;
+  readonly cwd: string;
+};
+
+export function resolveTailwindCli(deps: ResolveTailwindCliDeps): string | undefined {
+  if (deps.bun === undefined) return undefined;
+  try {
+    const pkgJsonPath = deps.bun.resolveSync("@tailwindcss/cli/package.json", deps.cwd);
+    // bin: { tailwindcss: "./dist/index.mjs" } → absoluter Pfad
+    return resolve(pkgJsonPath, "..", "dist", "index.mjs");
+  } catch {
+    return undefined;
+  }
+}