@cosmicdrift/kumiko-dev-server 0.1.0

package/src/scaffold-feature.ts

@@ -0,0 +1,226 @@
+// scaffoldFeature — generate a fresh feature workspace from a name.
+// Used by `yarn kumiko create <name>` and (later) by the Designer when
+// a tenant scaffolds a new feature inside their repo. Wraps the
+// canonical-form renderer (feature-ast/render.ts) so every freshly
+// scaffolded feature is born in canonical Object-Form with the
+// schema-version header set.
+//
+// The generated workspace is intentionally minimal: a single entity
+// pattern as a starter, so the user has something to point a "yarn
+// kumiko dev" at and immediately see something on screen. Adding more
+// patterns is the user's job (or the Designer's / AI's, on top of this
+// scaffolding).
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  type FeaturePattern,
+  renderFeatureFile,
+  type SourceLocation,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export type ScaffoldFeatureOptions = {
+  /** camelCase feature name. Must be a valid JS identifier. */
+  readonly name: string;
+  /**
+   * Absolute or repo-relative path where the feature workspace gets
+   * created. Defaults to `samples/recipes/<kebab-name>/` under the
+   * resolved repo root.
+   */
+  readonly destination?: string;
+  /** Repo root used to resolve the default destination. Defaults to cwd. */
+  readonly repoRoot?: string;
+};
+
+export type ScaffoldFeatureResult = {
+  readonly destination: string;
+  readonly featureFile: string;
+  readonly packageJsonFile: string;
+  readonly tsconfigFile: string;
+  readonly featureName: string;
+  readonly packageName: string;
+};
+
+/**
+ * Generate a starter feature workspace at `destination`. Throws when
+ * the destination already exists — refuses to overwrite. The caller is
+ * expected to run `yarn install` afterwards to wire the workspace.
+ */
+export function scaffoldFeature(options: ScaffoldFeatureOptions): ScaffoldFeatureResult {
+  const featureName = validateFeatureName(options.name);
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const kebab = camelToKebab(featureName);
+  const destination = resolve(
+    options.destination
+      ? resolveDestination(options.destination, repoRoot)
+      : join(repoRoot, "samples", "recipes", kebab),
+  );
+
+  if (existsSync(destination)) {
+    throw new Error(
+      `scaffoldFeature: destination already exists at ${destination} — refusing to overwrite`,
+    );
+  }
+
+  mkdirSync(join(destination, "src"), { recursive: true });
+
+  const packageName = `@cosmicdrift/kumiko-sample-${kebab}`;
+  const packageJson = renderPackageJson(packageName);
+  const packageJsonFile = join(destination, "package.json");
+  writeFileSync(packageJsonFile, packageJson);
+
+  const tsconfigFile = join(destination, "tsconfig.json");
+  writeFileSync(tsconfigFile, renderTsconfig());
+
+  const featureFile = join(destination, "src", "feature.ts");
+  const featureSource = renderFeatureFile({
+    featureName,
+    patterns: starterPatterns(),
+  });
+  writeFileSync(featureFile, featureSource);
+
+  return {
+    destination,
+    featureFile,
+    packageJsonFile,
+    tsconfigFile,
+    featureName,
+    packageName,
+  };
+}
+
+// =============================================================================
+// Internal — name + path validation
+// =============================================================================
+
+const RESERVED_WORDS: ReadonlySet<string> = new Set([
+  // Subset of TS reserved words that would be confusing as feature names.
+  "default",
+  "delete",
+  "function",
+  "import",
+  "export",
+  "class",
+  "interface",
+  "enum",
+  "type",
+  "module",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "static",
+  "void",
+  "null",
+  "true",
+  "false",
+]);
+
+const NAME_RE = /^[a-z][A-Za-z0-9]*$/;
+
+function validateFeatureName(raw: string): string {
+  if (!raw) {
+    throw new Error("scaffoldFeature: feature name is required");
+  }
+  if (!NAME_RE.test(raw)) {
+    throw new Error(
+      `scaffoldFeature: "${raw}" is not a valid feature name — use camelCase starting with a lowercase letter (e.g. "todoList")`,
+    );
+  }
+  if (RESERVED_WORDS.has(raw)) {
+    throw new Error(`scaffoldFeature: "${raw}" is a reserved word and cannot be a feature name`);
+  }
+  return raw;
+}
+
+function camelToKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+function resolveDestination(dest: string, repoRoot: string): string {
+  // Allow callers to pass either an absolute path or a repo-relative
+  // one — keep both ergonomic. `resolve(repoRoot, dest)` is a no-op for
+  // absolute paths.
+  return resolve(repoRoot, dest);
+}
+
+// =============================================================================
+// Internal — content generators
+// =============================================================================
+
+function renderPackageJson(packageName: string): string {
+  return `${JSON.stringify(
+    {
+      name: packageName,
+      description: "Kumiko sample feature — scaffolded by `yarn kumiko create`",
+      private: true,
+      dependencies: {
+        "@cosmicdrift/kumiko-framework": "workspace:*",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Standard tsconfig matching the rest of the sample workspaces:
+ * strict, ESNext, bundler-resolution, no-emit. Without this file
+ * `yarn install + tsc` immediately complains about missing config —
+ * scaffolded features should compile cleanly out of the box.
+ */
+function renderTsconfig(): string {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        noPropertyAccessFromIndexSignature: true,
+        forceConsistentCasingInFileNames: true,
+        verbatimModuleSyntax: true,
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        esModuleInterop: true,
+        skipLibCheck: true,
+        lib: ["ESNext"],
+        types: ["bun-types"],
+        noEmit: true,
+      },
+      include: ["src/**/*"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+// Synthetic SourceLocation — the renderer reads `.raw` only for opaque
+// (closure-bearing) bodies. Static patterns like `entity` don't touch
+// `source.raw` at render-time, so an empty placeholder is fine.
+const SYNTHETIC_LOC: SourceLocation = {
+  file: "<scaffold>",
+  start: { line: 1, column: 1 },
+  end: { line: 1, column: 1 },
+  raw: "",
+};
+
+function starterPatterns(): readonly FeaturePattern[] {
+  // One entity, one field. Smallest interesting output: parses, renders,
+  // can be `yarn kumiko dev`'d, and gives the user something to extend.
+  return [
+    {
+      kind: "entity",
+      source: SYNTHETIC_LOC,
+      entityName: "item",
+      definition: {
+        fields: {
+          title: { type: "text", required: true },
+        },
+      },
+    },
+  ];
+}

package/src/try-hono-first.ts

@@ -0,0 +1,46 @@
+// Shared helper für die "Hono-first, SPA-fallback wenn 404"-Strategie.
+// Wird von dev (createKumikoServer.handleFetch) UND prod (runProdApp's
+// fetch-handler) verwendet — identische Semantik, ein helper. Ohne den
+// shared-Helper drifteten die beiden Pfade silent (genau der Bug der
+// legal-pages im dev-server geshadowed hat — runProdApp's docs sagten
+// "Hono matched VOR fallback", dev-server tat das NICHT).
+//
+// Pattern:
+//   1. Try app.fetch(req) — wenn Hono eine route matcht, greift sie.
+//   2. 404 vom Hono-stack → null returnen, caller macht SPA-fallback.
+//   3. Sonstige status (200, 401, 500, ...) → response durchreichen.
+//
+// req.clone() weil downstream der req body nochmal lesbar sein muss
+// (POST/PUT/PATCH future-proof — heute nur GET-routes betroffen).
+
+export type HonoLikeApp = {
+  // Hono.app.fetch ist `(req) => Response | Promise<Response>` (sync wenn
+  // alle Handler sync sind, sonst Promise). createApiEntrypoint's
+  // apiHandler matcht dieselbe shape. Union accepts both — wir await
+  // unten, das funktioniert für beide Fälle.
+  readonly fetch: (req: Request) => Response | Promise<Response>;
+};
+
+export type HonoFirstResult = {
+  /** True wenn Hono eine matchende Route hat (status !== 404).
+   *  Caller returnt dann response direkt.
+   *  False wenn keine Route matcht (status === 404). Caller macht den
+   *  SPA-/static-fallback; response enthält den 404 als final-fallback
+   *  falls auch der SPA-Pfad nichts liefert. */
+  readonly matched: boolean;
+  readonly response: Response;
+};
+
+/**
+ * Hono-first try: app.fetch ZUERST. Wenn matched (status !== 404), gibt
+ * der caller den response direkt zurück. Wenn nicht matched, fällt der
+ * caller in den eigenen SPA-/static-fallback zurück — der response (404)
+ * bleibt verfügbar als letztes Sicherheitsnetz.
+ *
+ * req.clone() weil downstream der req body nochmal lesbar sein muss
+ * (POST/PUT/PATCH future-proof — heute nur GET-routes betroffen).
+ */
+export async function tryHonoFirst(app: HonoLikeApp, req: Request): Promise<HonoFirstResult> {
+  const response = await app.fetch(req.clone());
+  return { matched: response.status !== 404, response };
+}