@xemahq/create-biome 0.2.3 → 0.3.1

package/src/lib/manifest-builder.ts

@@ -0,0 +1,376 @@
+/**
+ * Build the `xema-biome.json` manifest object for a freshly-scaffolded biome.
+ *
+ * The shape MUST match the canonical `BiomeManifestSchema`
+ * (`@xemahq/kernel-contracts/biome`): the WRAPPED
+ * `{ name, version, xema: { id, displayName, scope, target, … } }` form. The
+ * legacy flat `{ schemaVersion, id, trustTier, contributes }` shape this
+ * builder used to emit was schema-INVALID and would have been rejected by the
+ * biome host at boot — it is gone, no compat shim.
+ *
+ * Manifest invariants enforced here so generated biomes never start life with
+ * an invalid file:
+ *   - `xema.id` is kebab-case and MUST equal the biome folder name (the
+ *     `check-biome-layout.mjs` boundary check enforces this).
+ *   - `name` is the conventional first-party scoped package name
+ *     `@xemahq/biomes-<id>` — first-party because the scaffold targets in-tree
+ *     biomes the platform runs, not external npm packages.
+ *   - `xema.scope` defaults to `platform` (a first-party domain biome — see
+ *     {@link DEFAULT_BIOME_SCOPE}).
+ *   - The default manifest is the SMALLEST viable server biome: every
+ *     optional block the author has not asked for is ABSENT, never emitted
+ *     as an empty array/object. Absent beats empty — the schema treats both
+ *     the same, and an absent block never teaches a stale shape.
+ */
+
+/** Manifest-shape scope tier — value-identical to the kernel `BiomeTier` set. */
+export type ManifestScope = 'kernel' | 'system' | 'base' | 'platform';
+
+/**
+ * Default `xema.scope` for a freshly-scaffolded biome. `platform` is the L3
+ * first-party domain/connector tier — where a new product biome belongs.
+ * Foundational tiers (`base`, `system`, `kernel`) are deliberate choices the
+ * author opts into via `--scope`.
+ */
+export const DEFAULT_BIOME_SCOPE: ManifestScope = 'platform';
+
+/**
+ * Default `xema.display.icon` for a freshly-scaffolded biome. A biome is a
+ * pluggable unit, so `puzzle` reads as a sensible generic glyph. Giving it a
+ * default means an author in a hurry to test never has to pick one — the biome
+ * still renders with a real icon in the installed-biomes view and picker, and
+ * the author can refine it later. (`icon`/`category` are free-string keys the
+ * host resolves; see `BiomeDisplaySchema`.)
+ */
+export const DEFAULT_BIOME_ICON = 'puzzle';
+
+/**
+ * Default `xema.display.category`. New biomes are L3 domain/capability biomes,
+ * so they group under `build` (the lowercase `NavCategory` value the host rail
+ * + biome picker use). Overridable, but a real default beats an unset field.
+ */
+export const DEFAULT_BIOME_CATEGORY = 'build';
+
+/** A biome's `display` block (icon/category/summary), emitted with real defaults. */
+export interface ManifestDisplay {
+  readonly icon: string;
+  readonly category: string;
+  readonly summary: string;
+}
+
+export interface ServerManifestBuilderInput {
+  readonly biomeId: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly scope: ManifestScope;
+  /** Name of the single NestJS API shipped under `api/<apiName>/`. */
+  readonly apiName: string;
+  /**
+   * Optional display overrides. Any field omitted falls back to a real default
+   * (icon → {@link DEFAULT_BIOME_ICON}, category → {@link DEFAULT_BIOME_CATEGORY},
+   * summary → `description`) so a scaffolded biome always has a complete,
+   * renderable `display` block.
+   */
+  readonly display?: Partial<ManifestDisplay>;
+  /** Optional, non-mandatory keyword/hashtag tags for search + grouping. */
+  readonly tags?: readonly string[];
+}
+
+export interface WebManifestBuilderInput {
+  readonly biomeId: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly scope: ManifestScope;
+  /** Server biome ids this web surface requires (its backend counterpart). */
+  readonly requiresServerBiomes: readonly string[];
+  /** Optional display overrides (see {@link ServerManifestBuilderInput.display}). */
+  readonly display?: Partial<ManifestDisplay>;
+  /** Optional, non-mandatory keyword/hashtag tags. */
+  readonly tags?: readonly string[];
+}
+
+/**
+ * Resolve a complete `display` block from optional author overrides + defaults.
+ * `summary` defaults to the biome description so the tile is never blank.
+ */
+function resolveDisplay(
+  description: string,
+  overrides: Partial<ManifestDisplay> | undefined,
+): ManifestDisplay {
+  return {
+    icon: overrides?.icon?.trim() || DEFAULT_BIOME_ICON,
+    category: overrides?.category?.trim() || DEFAULT_BIOME_CATEGORY,
+    summary: overrides?.summary?.trim() || description,
+  };
+}
+
+/** Only emit `tags` when the author actually supplied non-empty ones (absent beats empty). */
+function normalizeTags(tags: readonly string[] | undefined): readonly string[] | undefined {
+  const cleaned = (tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
+/**
+ * The one API declaration the default scaffold ships. `requiresServices`
+ * stays EXPLICIT (`['identity-api']` — the floor every biome-api needs)
+ * because it matches what `generate-service-bootstrap.mjs` emits into the
+ * seeded descriptor; every genuinely optional field (`exposesCapabilities`,
+ * `image`, `scopes`, …) is absent, not empty.
+ */
+export interface ServerApiDeclaration {
+  readonly name: string;
+  readonly path: string;
+  readonly displayName: string;
+  readonly serviceKind: 'biome-api';
+  readonly requiresServices: readonly string[];
+}
+
+/**
+ * The smallest viable server-biome manifest: identity + capability domain +
+ * engines + ONE api. Optional blocks (`requiresCapabilities`,
+ * `exposesCapabilities`, `contributions`, `webhookFilters`, `mcpTools`,
+ * `provisioning`, …) are NOT part of the default shape — the host applies the
+ * same defaults whether they are absent or empty (e.g. the contributions
+ * directory defaults to `contributions/` with no manifest block), so the
+ * scaffold omits them.
+ *
+ * `capabilityDomain` is the ONE exception to "absent beats empty". The
+ * projector defaults it to `xema.id`, so emitting `capabilityDomain: <id>` is
+ * value-redundant — but it is the ONLY declaration that controls the `<domain>`
+ * segment of every capability the biome's routes project, and an author who
+ * never sees the field has no way to learn the knob exists. It is emitted so
+ * renaming the biome's capability vocabulary is a one-line edit rather than a
+ * documentation hunt.
+ */
+export interface ServerManifestObject {
+  readonly name: string;
+  readonly version: string;
+  readonly xema: {
+    readonly id: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly display: ManifestDisplay;
+    readonly scope: ManifestScope;
+    readonly target: 'server';
+    readonly capabilityDomain: string;
+    readonly engines: { readonly xema: string };
+    readonly ships: { readonly apis: readonly ServerApiDeclaration[] };
+    readonly tags?: readonly string[];
+  };
+}
+
+/**
+ * A connector biome's manifest. `xema.kind: "connector"` is a MARKER with
+ * teeth: `tooling/boundaries/check-connector-biome.mjs` requires the biome to
+ * contribute ≥1 `connector-adapter`, to ship no product surface (no web target,
+ * no pages, no BFF), and to depend on/extend no other biome. The scaffolded
+ * connector satisfies all three, so a generated connector is CI-clean on
+ * creation.
+ *
+ * `contributes` is the declared whitelist the guard reads; the descriptors
+ * themselves live in the `ConnectorAdapterModule` the biome ships, NOT in a
+ * parallel `*.connector-adapter.contribution.json`. One source, not two — a
+ * hand-written descriptor file duplicating the module would be exactly the
+ * drift this scaffold exists to prevent.
+ */
+export interface ConnectorManifestObject {
+  readonly name: string;
+  readonly version: string;
+  readonly xema: {
+    readonly id: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly display: ManifestDisplay;
+    readonly scope: ManifestScope;
+    readonly target: 'server';
+    readonly kind: 'connector';
+    readonly capabilityDomain: string;
+    readonly trustTier: 'first-party';
+    readonly engines: { readonly xema: string };
+    readonly contributes: readonly ['connector-adapter'];
+    readonly tags?: readonly string[];
+  };
+}
+
+export interface WebManifestObject {
+  readonly name: string;
+  readonly version: string;
+  readonly xema: {
+    readonly id: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly display: ManifestDisplay;
+    readonly scope: ManifestScope;
+    readonly target: 'web';
+    readonly requiresServerBiomes?: readonly string[];
+    readonly tags?: readonly string[];
+  };
+}
+
+const XEMA_ENGINE_RANGE = '^1.0.0';
+
+/**
+ * Default services every biome-api needs to bootstrap. `identity-api` is the
+ * floor (the generated bootstrap descriptor falls back to it when none is
+ * declared); we make it explicit so the scaffolded manifest reads as a real
+ * one would.
+ */
+const DEFAULT_API_REQUIRES_SERVICES: readonly string[] = ['identity-api'];
+
+export function buildServerManifest(
+  input: ServerManifestBuilderInput,
+): ServerManifestObject {
+  const tags = normalizeTags(input.tags);
+  return {
+    name: firstPartyPackageName(input.biomeId),
+    version: '0.1.0',
+    xema: {
+      id: input.biomeId,
+      displayName: input.displayName,
+      description: input.description,
+      display: resolveDisplay(input.description, input.display),
+      scope: input.scope,
+      target: 'server',
+      capabilityDomain: input.biomeId,
+      engines: { xema: XEMA_ENGINE_RANGE },
+      ships: {
+        apis: [
+          {
+            name: input.apiName,
+            path: `./api/${input.apiName}`,
+            displayName: `${input.displayName} API`,
+            serviceKind: 'biome-api',
+            requiresServices: DEFAULT_API_REQUIRES_SERVICES,
+          },
+        ],
+      },
+      ...(tags ? { tags } : {}),
+    },
+  };
+}
+
+export interface ConnectorManifestBuilderInput {
+  readonly biomeId: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly scope: ManifestScope;
+  /** Optional display overrides (see {@link ServerManifestBuilderInput.display}). */
+  readonly display?: Partial<ManifestDisplay>;
+  /** Optional, non-mandatory keyword/hashtag tags. */
+  readonly tags?: readonly string[];
+}
+
+/**
+ * Default `xema.display.icon` for a connector biome. `plug` is the glyph the
+ * first-party connector biomes use, so a scaffolded connector renders
+ * alongside them in the store catalog rather than as a generic puzzle piece.
+ */
+export const DEFAULT_CONNECTOR_ICON = 'plug';
+
+/** Default `xema.display.category` for a connector biome — the connect rail. */
+export const DEFAULT_CONNECTOR_CATEGORY = 'connect';
+
+export function buildConnectorManifest(
+  input: ConnectorManifestBuilderInput,
+): ConnectorManifestObject {
+  const tags = normalizeTags(input.tags);
+  return {
+    name: firstPartyPackageName(input.biomeId),
+    version: '0.1.0',
+    xema: {
+      id: input.biomeId,
+      displayName: input.displayName,
+      description: input.description,
+      display: {
+        icon: input.display?.icon?.trim() || DEFAULT_CONNECTOR_ICON,
+        category: input.display?.category?.trim() || DEFAULT_CONNECTOR_CATEGORY,
+        summary: input.display?.summary?.trim() || input.description,
+      },
+      scope: input.scope,
+      target: 'server',
+      kind: 'connector',
+      capabilityDomain: input.biomeId,
+      // A scaffolded connector is generated INTO a first-party tree by an
+      // author who owns it. `trustTier` defaults to `third-party` when absent,
+      // which would mis-file it; declaring it is the honest default here and a
+      // one-word edit for an author vendoring someone else's adapter.
+      trustTier: 'first-party',
+      engines: { xema: XEMA_ENGINE_RANGE },
+      contributes: ['connector-adapter'],
+      ...(tags ? { tags } : {}),
+    },
+  };
+}
+
+export function buildWebManifest(
+  input: WebManifestBuilderInput,
+): WebManifestObject {
+  const tags = normalizeTags(input.tags);
+  const base: WebManifestObject = {
+    name: firstPartyPackageName(input.biomeId),
+    version: '0.1.0',
+    xema: {
+      id: input.biomeId,
+      displayName: input.displayName,
+      description: input.description,
+      display: resolveDisplay(input.description, input.display),
+      scope: input.scope,
+      target: 'web' as const,
+      ...(tags ? { tags } : {}),
+    },
+  };
+  if (input.requiresServerBiomes.length === 0) {
+    return base;
+  }
+  return {
+    ...base,
+    xema: { ...base.xema, requiresServerBiomes: input.requiresServerBiomes },
+  };
+}
+
+/**
+ * Conventional first-party biome package name `@xemahq/biomes-<id>`. The
+ * scaffold emits in-tree first-party biomes (the platform runs them), so this
+ * is the right shape — NOT the external `@xemahq-biomes/<id>` form the old
+ * external-package scaffolder used.
+ */
+export function firstPartyPackageName(biomeId: string): string {
+  return `@xemahq/biomes-${biomeId}`;
+}
+
+/**
+ * The single NestJS API a service/full biome ships, by convention
+ * `<id>-api` under `api/<id>-api/`.
+ */
+export function apiNameForBiome(biomeId: string): string {
+  return `${biomeId}-api`;
+}
+
+/**
+ * Web biomes are conventionally suffixed `-web` (their id, package name, and
+ * directory all carry the suffix), so a server biome and its paired web
+ * surface never collide.
+ */
+export function webBiomeId(biomeId: string): string {
+  return `${biomeId}-web`;
+}
+
+/**
+ * Validate the biome id rules the manifest enforces. Centralized so the CLI
+ * fails fast on bad input instead of generating a folder the biome host
+ * rejects at boot. Pattern matches `BiomeIdSchema` (kebab-case) plus a
+ * 3–63-char length floor.
+ */
+const BIOME_ID_PATTERN = /^[a-z][a-z0-9-]{1,61}[a-z0-9]$/;
+
+export function validateBiomeId(
+  biomeId: string,
+): { ok: true } | { ok: false; reason: string } {
+  if (!BIOME_ID_PATTERN.test(biomeId)) {
+    return {
+      ok: false,
+      reason: `biome id "${biomeId}" must be kebab-case (lowercase letters/digits + dashes), 3-63 chars, starting with a letter`,
+    };
+  }
+  return { ok: true };
+}

package/src/lib/scaffolder.ts

@@ -0,0 +1,259 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+
+import { BiomeKind } from './kind.js';
+import {
+  apiNameForBiome,
+  buildConnectorManifest,
+  buildServerManifest,
+  buildWebManifest,
+  validateBiomeId,
+  webBiomeId,
+  type ManifestScope,
+} from './manifest-builder.js';
+import {
+  connectorBiomeFiles,
+  renderServerBiomeFiles,
+  webBiomeFiles,
+  type TemplateContext,
+} from './template-files.js';
+
+/**
+ * Pure-data description of a biome to be scaffolded. The CLI builds this from
+ * user prompts and hands it to `scaffoldBiome` — keeping the scaffolder itself
+ * agnostic of whether inputs came from prompts, CLI flags, or a programmatic
+ * caller (e.g. tests).
+ */
+export interface ScaffoldBiomeInput {
+  readonly biomeId: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly kind: BiomeKind;
+  readonly scope: ManifestScope;
+  /**
+   * Monorepo root. The scaffolder writes server biomes under
+   * `<repoRoot>/<serverBiomesDir>/<id>/` and web biomes under
+   * `<repoRoot>/<webBiomesDir>/<tier>/<id>-web/`. Defaults are derived from
+   * the standard layout; tests pass a scratch root.
+   */
+  readonly repoRoot: string;
+  /**
+   * Directory (relative to repoRoot) where in-tree SERVER biomes live, e.g.
+   * `repos/xema-community/biomes`. Required for `service`/`full`.
+   */
+  readonly serverBiomesDir?: string;
+  /**
+   * Directory (relative to repoRoot) where host-web WEB biomes live, e.g.
+   * `submodules/xema-host-web/biomes`. Required for `web`/`full`. The biome is
+   * placed under `<webBiomesDir>/<scope-tier>/<id>-web/`.
+   */
+  readonly webBiomesDir?: string;
+}
+
+export interface ScaffoldedBiomeDir {
+  readonly target: 'server' | 'web';
+  readonly dir: string;
+}
+
+export interface ScaffoldBiomeResult {
+  readonly dirs: readonly ScaffoldedBiomeDir[];
+  readonly filesWritten: readonly string[];
+}
+
+/**
+ * Generate a new in-tree biome (server, web, or full-stack). Fails fast on:
+ *   - malformed biome id (kebab-case 3–63 chars)
+ *   - any target directory already exists (refuse to overwrite)
+ *   - a required base directory not provided for the chosen kind
+ *
+ * Returns the directories created and the absolute paths of every file
+ * written so the CLI can render its own "next steps" output.
+ */
+export async function scaffoldBiome(
+  input: ScaffoldBiomeInput,
+): Promise<ScaffoldBiomeResult> {
+  const idCheck = validateBiomeId(input.biomeId);
+  if (!idCheck.ok) {
+    throw new ScaffolderError(idCheck.reason);
+  }
+
+  const dirs: ScaffoldedBiomeDir[] = [];
+  const filesWritten: string[] = [];
+
+  const wantsServer =
+    input.kind === BiomeKind.Service || input.kind === BiomeKind.Full;
+  const wantsWeb = input.kind === BiomeKind.Web || input.kind === BiomeKind.Full;
+
+  if (input.kind === BiomeKind.Connector) {
+    const connectorDir = resolveServerDir(input);
+    refuseExisting(connectorDir);
+    await writeConnectorBiome(input, connectorDir, filesWritten);
+    // A connector is a server-target biome; it simply ships an adapter module
+    // instead of an API. It never has a paired web surface — the connector
+    // boundary check rejects one — so this returns here.
+    return { dirs: [{ target: 'server', dir: connectorDir }], filesWritten };
+  }
+
+  if (wantsServer) {
+    const serverDir = resolveServerDir(input);
+    refuseExisting(serverDir);
+    await writeServerBiome(input, serverDir, filesWritten);
+    dirs.push({ target: 'server', dir: serverDir });
+  }
+
+  if (wantsWeb) {
+    const webDir = resolveWebDir(input);
+    refuseExisting(webDir);
+    await writeWebBiome(input, webDir, filesWritten);
+    dirs.push({ target: 'web', dir: webDir });
+  }
+
+  return { dirs, filesWritten };
+}
+
+function resolveServerDir(input: ScaffoldBiomeInput): string {
+  if (!input.serverBiomesDir) {
+    throw new ScaffolderError(
+      'serverBiomesDir is required for a service/full biome (e.g. repos/xema-community/biomes)',
+    );
+  }
+  return path.resolve(input.repoRoot, input.serverBiomesDir, input.biomeId);
+}
+
+function resolveWebDir(input: ScaffoldBiomeInput): string {
+  if (!input.webBiomesDir) {
+    throw new ScaffolderError(
+      'webBiomesDir is required for a web/full biome (e.g. submodules/xema-host-web/biomes)',
+    );
+  }
+  // Web biomes are tiered by scope under the host tree (platform|system|…).
+  const tier = input.scope;
+  return path.resolve(
+    input.repoRoot,
+    input.webBiomesDir,
+    tier,
+    webBiomeId(input.biomeId),
+  );
+}
+
+function refuseExisting(dir: string): void {
+  if (existsSync(dir)) {
+    throw new ScaffolderError(
+      `target directory already exists: ${dir} — choose a fresh id or delete it first`,
+    );
+  }
+}
+
+async function writeServerBiome(
+  input: ScaffoldBiomeInput,
+  serverDir: string,
+  written: string[],
+): Promise<void> {
+  const ctx: TemplateContext = {
+    biomeId: input.biomeId,
+    displayName: input.displayName,
+    description: input.description,
+  };
+  const manifest = buildServerManifest({
+    biomeId: input.biomeId,
+    displayName: input.displayName,
+    description: input.description,
+    scope: input.scope,
+    apiName: apiNameForBiome(input.biomeId),
+  });
+  await mkdir(serverDir, { recursive: true });
+  await writeJson(serverDir, 'xema-biome.json', manifest, written);
+  for (const [rel, content] of Object.entries(renderServerBiomeFiles(ctx))) {
+    await writeText(serverDir, rel, content, written);
+  }
+}
+
+async function writeConnectorBiome(
+  input: ScaffoldBiomeInput,
+  connectorDir: string,
+  written: string[],
+): Promise<void> {
+  const ctx: TemplateContext = {
+    biomeId: input.biomeId,
+    displayName: input.displayName,
+    description: input.description,
+  };
+  const manifest = buildConnectorManifest({
+    biomeId: input.biomeId,
+    displayName: input.displayName,
+    description: input.description,
+    scope: input.scope,
+  });
+  await mkdir(connectorDir, { recursive: true });
+  await writeJson(connectorDir, 'xema-biome.json', manifest, written);
+  for (const [rel, content] of Object.entries(connectorBiomeFiles(ctx))) {
+    await writeText(connectorDir, rel, content, written);
+  }
+}
+
+async function writeWebBiome(
+  input: ScaffoldBiomeInput,
+  webDir: string,
+  written: string[],
+): Promise<void> {
+  const wid = webBiomeId(input.biomeId);
+  const navLabel = input.displayName;
+  const manifest = buildWebManifest({
+    biomeId: wid,
+    displayName: `${input.displayName} (Web)`,
+    description: input.description,
+    scope: input.scope,
+    // A full-stack biome's web surface requires its server counterpart; a
+    // standalone web biome requires none by default (the author wires it).
+    requiresServerBiomes:
+      input.kind === BiomeKind.Full ? [input.biomeId] : [],
+  });
+  await mkdir(webDir, { recursive: true });
+  await writeJson(webDir, 'xema-biome.json', manifest, written);
+  for (const [rel, content] of Object.entries(
+    webBiomeFiles({
+      biomeId: input.biomeId,
+      displayName: input.displayName,
+      description: input.description,
+      webBiomeId: wid,
+      navLabel,
+    }),
+  )) {
+    await writeText(webDir, rel, content, written);
+  }
+}
+
+/**
+ * Errors the scaffolder throws are always operator-readable (no stack-trace
+ * value-add). The CLI uses the dedicated type to render them with a clean
+ * prefix and exit code 1 — anything else surfaces with full trace.
+ */
+export class ScaffolderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ScaffolderError';
+  }
+}
+
+async function writeJson(
+  root: string,
+  relativePath: string,
+  data: unknown,
+  written: string[],
+): Promise<void> {
+  const json = `${JSON.stringify(data, null, 2)}\n`;
+  await writeText(root, relativePath, json, written);
+}
+
+async function writeText(
+  root: string,
+  relativePath: string,
+  content: string,
+  written: string[],
+): Promise<void> {
+  const absolute = path.join(root, relativePath);
+  await mkdir(path.dirname(absolute), { recursive: true });
+  await writeFile(absolute, content, 'utf8');
+  written.push(absolute);
+}