feat(ui+chat): adapter layer (#3090) + chat composition-rules port (#2980) — backward-compatible

cli/commands/generate/adapter-generator.test.ts

@@ -0,0 +1,69 @@
+import "#veryfront/schemas/_test-setup.ts";
+/**
+ * Tests for `veryfront generate adapter <engine>` — vendoring a veryfront/ui
+ * engine adapter template into a consumer project.
+ */
+import { assert, assertRejects, assertStringIncludes } from "#veryfront/testing/assert.ts";
+import { describe, it } from "#veryfront/testing/bdd.ts";
+import { join } from "#std/path.ts";
+import { generateUiAdapter } from "./adapter-generator.ts";
+import { getUiAdapterTemplate, listUiAdapters } from "../../templates/loader.ts";
+
+describe("commands/generate/adapter-generator", () => {
+  it("the manifest ships the four engine templates", () => {
+    const engines = listUiAdapters();
+    for (const engine of ["base-ui", "radix", "react-aria", "ariakit"]) {
+      assert(engines.includes(engine), `manifest missing ui-adapter:${engine}`);
+    }
+  });
+
+  it("base-ui template maps the overlay archetypes + exports its adapter", () => {
+    const files = getUiAdapterTemplate("base-ui");
+    assert(files && files.length === 1, "base-ui template should be one file");
+    const src = files![0]!.content;
+    for (const slot of ["popover:", "dialog:", "menu:", "tooltip:"]) {
+      assertStringIncludes(src, slot);
+    }
+    assertStringIncludes(src, "baseUiAdapter");
+  });
+
+  it("vendors ui-adapters/<engine>.tsx into the project", async () => {
+    const dir = await Deno.makeTempDir();
+    try {
+      await generateUiAdapter(dir, "radix");
+      const dest = join(dir, "ui-adapters", "radix.tsx");
+      const written = await Deno.readTextFile(dest);
+      assertStringIncludes(written, "radixAdapter");
+      assertStringIncludes(written, "REFERENCE TEMPLATE");
+    } finally {
+      await Deno.remove(dir, { recursive: true });
+    }
+  });
+
+  it("does not clobber an already-vendored adapter", async () => {
+    const dir = await Deno.makeTempDir();
+    try {
+      await Deno.mkdir(join(dir, "ui-adapters"));
+      const dest = join(dir, "ui-adapters", "base-ui.tsx");
+      await Deno.writeTextFile(dest, "// my edited adapter\n");
+      await generateUiAdapter(dir, "base-ui");
+      const after = await Deno.readTextFile(dest);
+      assert(after === "// my edited adapter\n", "must not overwrite a vendored file");
+    } finally {
+      await Deno.remove(dir, { recursive: true });
+    }
+  });
+
+  it("rejects an unknown engine with the available list", async () => {
+    const dir = await Deno.makeTempDir();
+    try {
+      await assertRejects(
+        () => generateUiAdapter(dir, "not-an-engine"),
+        Error,
+        "Unknown ui adapter engine",
+      );
+    } finally {
+      await Deno.remove(dir, { recursive: true });
+    }
+  });
+});

cli/commands/generate/adapter-generator.ts

@@ -0,0 +1,86 @@
+/**
+ * `veryfront generate adapter <engine>` — vendor a `veryfront/ui` engine adapter.
+ *
+ * Copies the `<engine>.tsx` reference template (Base UI / Radix / React Aria /
+ * Ariakit) verbatim into the consumer's `./ui-adapters/`. From then on the
+ * consumer OWNS the file and the engine package is THEIR dependency — `veryfront/ui`
+ * core stays engine-free (enforced by a CI guard), so the swap is opt-in and the
+ * engine version is on the consumer's schedule. Wire it up once via
+ * `<UIAdapterProvider adapter={<engine>Adapter}>` (see the file's docstring).
+ *
+ * @module cli/commands/generate/adapter-generator
+ */
+import { join } from "#std/path.ts";
+import { bold, brand, dim } from "#cli/ui";
+import { cliLogger } from "#cli/utils";
+import { createFileSystem } from "veryfront/platform";
+import { createError, toError } from "veryfront/errors";
+import { ensureDir } from "../../utils/fs.ts";
+import { getUiAdapterTemplate, listUiAdapters } from "../../templates/loader.ts";
+
+/** npm package + wiring hint per engine, shown after scaffolding. */
+const ENGINE_PACKAGES: Record<string, { pkg: string; adapter: string }> = {
+  "base-ui": { pkg: "@base-ui/react", adapter: "baseUiAdapter" },
+  radix: {
+    pkg:
+      "@radix-ui/react-popover @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-tooltip",
+    adapter: "radixAdapter",
+  },
+  "react-aria": { pkg: "react-aria-components", adapter: "reactAriaAdapter" },
+  ariakit: { pkg: "@ariakit/react", adapter: "ariakitAdapter" },
+  vaul: { pkg: "vaul", adapter: "vaulAdapter" },
+};
+
+/** Scaffold `ui-adapters/<engine>.tsx` into the project (idempotent — never clobbers). */
+export async function generateUiAdapter(
+  projectDir: string,
+  engine: string,
+): Promise<void> {
+  const files = getUiAdapterTemplate(engine);
+  if (!files || files.length === 0) {
+    const available = listUiAdapters();
+    throw toError(
+      createError({
+        type: "config",
+        message: available.length
+          ? `Unknown ui adapter engine "${engine}". Available: ${available.join(", ")}`
+          : `No ui adapter engines are available in this build.`,
+      }),
+    );
+  }
+
+  const fs = createFileSystem();
+  const targetDir = join(projectDir, "ui-adapters");
+  await ensureDir(targetDir);
+
+  const written: string[] = [];
+  for (const file of files) {
+    const dest = join(targetDir, file.path);
+    if (await fs.exists(dest)) {
+      cliLogger.warn(
+        `ui-adapters/${file.path} already exists — left as-is (delete it to regenerate).`,
+      );
+      continue;
+    }
+    await fs.writeTextFile(dest, file.content);
+    written.push(`ui-adapters/${file.path}`);
+  }
+
+  const meta = ENGINE_PACKAGES[engine];
+  for (const path of written) cliLogger.info(`Created ${brand(path)}`);
+  cliLogger.info("");
+  cliLogger.info(bold("Next steps:"));
+  if (meta) {
+    cliLogger.info(`  1. Install the engine:  ${brand(`npm i ${meta.pkg}`)}`);
+    cliLogger.info(
+      `  2. Wrap your app:       ${
+        brand(`<UIAdapterProvider adapter={${meta.adapter}}>…</UIAdapterProvider>`)
+      }`,
+    );
+  }
+  cliLogger.info(
+    dim(
+      "  You own this file now. veryfront/ui core stays engine-free; slots you don't map fall back to builtin.",
+    ),
+  );
+}

cli/commands/generate/command-help.ts

@@ -19,9 +19,12 @@ export const generateHelp: CommandHelp = {
     "veryfront generate skill code-review",
     "veryfront generate integration             # Interactive wizard",
     "veryfront generate integration twilio      # With name preset",
+    "veryfront generate adapter base-ui         # Vendor a veryfront/ui engine adapter",
+    "veryfront generate adapter radix",
   ],
   notes: [
-    "Types: page, api, layout, component, tool, agent, prompt, workflow, task, resource, skill, integration",
+    "Types: page, api, layout, component, tool, agent, prompt, workflow, task, resource, skill, integration, adapter",
     "Integration type launches interactive wizard if name not provided",
+    "Adapter type vendors a veryfront/ui engine adapter into ./ui-adapters/ (engines: base-ui, radix, react-aria, ariakit, vaul)",
   ],
 };

cli/commands/generate/command.ts

@@ -2,6 +2,7 @@ import { getConfig } from "veryfront/config";
 import { cliLogger } from "#cli/utils";
 import { createError, toError } from "veryfront/errors";
 import { generateIntegration } from "./integration-generator.ts";
+import { generateUiAdapter } from "./adapter-generator.ts";
 import { isScaffoldType, scaffoldProjectFile } from "../../scaffold/engine.ts";
 
 async function getPreferredRouter(
@@ -32,6 +33,11 @@ export async function generateCommand(
     return;
   }
 
+  if (type === "adapter") {
+    await generateUiAdapter(projectDir, name);
+    return;
+  }
+
   if (!isScaffoldType(type)) {
     throw toError(
       createError({

cli/commands/generate/handler.ts

@@ -10,7 +10,7 @@ import type { ParsedArgs } from "#cli/shared/types";
 import { cwd } from "veryfront/platform";
 import { SCAFFOLD_TYPES } from "../../scaffold/engine.ts";
 
-const VALID_TYPES = [...SCAFFOLD_TYPES, "integration"] as const;
+const VALID_TYPES = [...SCAFFOLD_TYPES, "integration", "adapter"] as const;
 
 const getGenerateArgsSchema = defineSchema((v) =>
   v.object({

cli/templates/loader.ts

@@ -60,7 +60,10 @@ export function getIntegrationTemplate(
 
 export function listTemplates(): string[] {
   return Object.keys(typedManifest.templates).filter(
-    (name) => !name.startsWith("integration:"),
+    (name) =>
+      !name.startsWith("integration:") &&
+      !name.startsWith("ui-adapter:") &&
+      !name.startsWith("ai-rules:"),
   );
 }
 
@@ -69,3 +72,18 @@ export function listIntegrations(): string[] {
     .filter((name) => name.startsWith("integration:"))
     .map((name) => name.replace("integration:", ""));
 }
+
+/** The `<engine>.tsx` reference adapter for `veryfront generate adapter <engine>`. */
+export function getUiAdapterTemplate(engine: string): TemplateFile[] | null {
+  const entry = typedManifest.templates[`ui-adapter:${engine}`];
+  if (!entry) return null;
+
+  return getSortedFiles(entry);
+}
+
+/** Engine names with a shippable `ui-adapters/<engine>.tsx` reference template. */
+export function listUiAdapters(): string[] {
+  return Object.keys(typedManifest.templates)
+    .filter((name) => name.startsWith("ui-adapter:"))
+    .map((name) => name.replace("ui-adapter:", ""));
+}