Skip to content

The Open Standard for Generative UI

4.0 KB
Raw Blame
import * as fs from "node:fs";
import * as path from "node:path";

import { CreateError } from "../../../lib/errors";

export const OVERLAYS_DIR = "overlays";
export const OVERLAY_MANIFEST = "manifest.json";

/**
 * Describes everything a framework overlay changes beyond the files it ships.
 * The overlay's own files are copied implicitly; each key below names one
 * other surface the overlay needs to touch.
 */
export type OverlayManifest = {
  /** Prompt label for `--backend-framework` / the interactive picker. */
  label?: string;
  /** Optional prompt description. */
  description?: string;
  /** Merged into the scaffolded package.json. */
  packageJson?: {
    dependencies?: Record<string, string>;
    devDependencies?: Record<string, string>;
    scripts?: Record<string, string>;
    /** Base-template dependencies this overlay makes redundant. */
    removeDependencies?: string[];
  };
  /** Applied after the overlay's files are copied. */
  files?: {
    /** Base-template paths this overlay supersedes, relative to the project root. */
    remove?: string[];
  };
  /** Printed after scaffolding. `{{packageManager}}` is substituted. */
  gettingStarted?: string;
};

export type TemplateOverlay = {
  dir: string;
  manifest: OverlayManifest;
};

export type OverlayChoice = {
  name: string;
  label: string;
  description?: string;
};

export function listOverlays(templateDir: string): OverlayChoice[] {
  const overlaysDir = path.join(templateDir, OVERLAYS_DIR);
  const extra: OverlayChoice[] = fs.existsSync(path.join(templateDir, "src/agent.ts"))
    ? [{ name: "langgraph", label: "LangGraph (default)" }]
    : [];
  if (!fs.existsSync(overlaysDir)) return extra;
  for (const entry of fs.readdirSync(overlaysDir, { withFileTypes: true })) {
    if (!entry.isDirectory()) continue;
    const manifestPath = path.join(overlaysDir, entry.name, OVERLAY_MANIFEST);
    if (!fs.existsSync(manifestPath)) continue;
    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as OverlayManifest;
    extra.push({
      name: entry.name,
      label: manifest.label ?? entry.name,
      description: manifest.description,
    });
  }
  extra.sort((a, b) => a.name.localeCompare(b.name));
  return extra;
}

export function resolveOverlay(
  templateDir: string,
  overlayName: string,
): TemplateOverlay | undefined {
  const overlayDir = path.join(templateDir, OVERLAYS_DIR, overlayName);
  const manifestPath = path.join(overlayDir, OVERLAY_MANIFEST);
  if (!fs.existsSync(manifestPath)) {
    // LangGraph lives directly in the base template. Older template catalogs
    // can still provide an overlay, which is resolved above this fallback.
    if (overlayName === "langgraph" && fs.existsSync(path.join(templateDir, "src/agent.ts"))) {
      return undefined;
    }
    const available = listOverlays(templateDir)
      .map((overlay) => overlay.name)
      .join(" | ");
    throw new CreateError(
      "template_missing",
      `Backend framework "${overlayName}" not found. Use: ${available}.`,
      "invalid_input",
      "INVALID_BACKEND_FRAMEWORK",
    );
  }

  return {
    dir: overlayDir,
    manifest: JSON.parse(fs.readFileSync(manifestPath, "utf8")) as OverlayManifest,
  };
}

function removeEmptyParentDirs(projectDir: string, removedRelativePath: string) {
  let dir = path.dirname(path.join(projectDir, removedRelativePath));

  while (true) {
    const relative = path.relative(projectDir, dir);
    if (!relative || relative.startsWith("..")) break;
    if (fs.readdirSync(dir).length > 0) break;
    fs.rmdirSync(dir);
    dir = path.dirname(dir);
  }
}

export function applyOverlay(projectDir: string, overlay?: TemplateOverlay) {
  if (!overlay) return;

  for (const entry of fs.readdirSync(overlay.dir)) {
    if (entry === OVERLAY_MANIFEST) continue;
    fs.cpSync(path.join(overlay.dir, entry), path.join(projectDir, entry), {
      recursive: true,
    });
  }

  for (const relativePath of overlay.manifest.files?.remove ?? []) {
    fs.rmSync(path.join(projectDir, relativePath), { recursive: true, force: true });
    removeEmptyParentDirs(projectDir, relativePath);
  }
}