import { execFile, execFileSync } from "child_process";
import fs from "fs";
import os from "os";
import path from "path";
import { fileURLToPath, pathToFileURL } from "url";

import {
  DISPATCH_WORKSPACE_ROOT_REDIRECTS,
  getWorkspaceAppIdValidationError,
} from "../shared/workspace-app-id.js";
import { setupAgentSymlinks } from "./setup-agents.js";
import {
  coreTemplates,
  getTemplate,
  allTemplateNames,
  type TemplateMeta,
} from "./templates-meta.js";
import { workspacifyApp, parseWorkspaceScope } from "./workspacify.js";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const REPO = "BuilderIO/agent-native";
const TEMPLATES_DIR = "templates";
const POSTGRES_DEPENDENCY_VERSION = "^3.4.9";
const STANDALONE_EXACT_DEPENDENCY_OVERRIDES: Record<string, string> = {
  "@react-router/dev": "8.1.0",
  "@react-router/fs-routes": "8.1.0",
  "react-router": "8.1.0",
};
const REACT_ROUTER_BUILD_DEPENDENCIES = [
  "@react-router/dev",
  "@react-router/fs-routes",
  "react-router",
  "vite",
] as const;
const MINIMUM_RELEASE_AGE_EXCLUDES = [
  '"@typescript/*"',
  '"@sentry/*"',
  "fast-xml-parser",
  "typescript",
  "typescript-7",
];
const FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES = [
  "*/CLAUDE.md",
  "*/.claude/skills",
];
const localPackageTarballs = new Map<string, string>();

/**
 * Tagged error for input that fails CLI-level validation (repo names, app
 * names, etc.). The Sentry `beforeSend` hook in cli/index.ts drops events
 * whose top-level exception type is `ValidationError` so we don't pollute
 * Sentry with expected user-input rejections.
 */
export class ValidationError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "ValidationError";
  }
}

/**
 * Move the primitive-first and chat on-ramps to the top of the list so they
 * line up with clack's default highlight.
 */
function onRampFirst(templates: TemplateMeta[]): TemplateMeta[] {
  return moveTemplatesToFront(templates, ["headless", "chat"]);
}

function moveTemplatesToFront(
  templates: TemplateMeta[],
  preferredNames: string[],
): TemplateMeta[] {
  const preferred = preferredNames
    .map((name) => templates.find((t) => t.name === name))
    .filter((template): template is TemplateMeta => Boolean(template));
  if (preferred.length === 0) return templates;
  const preferredSet = new Set(preferred.map((t) => t.name));
  return [...preferred, ...templates.filter((t) => !preferredSet.has(t.name))];
}

/** Primitive-first scaffold option appended to standalone pickers. */
const HEADLESS_OPTION = {
  name: "headless",
  label: "Headless",
  hint: "Action-first app with one hello primitive and no UI shell",
};

export interface CreateAppOptions {
  /** Pre-select these templates in the picker. Comma-separated string or array. */
  template?: string;
  /** Scaffold a single standalone app (old behavior). Skips workspace creation. */
  standalone?: boolean;
  /** Internal: skip pnpm install at the end (for tests). */
  noInstall?: boolean;
  /**
   * Internal: always scaffold a workspace and skip the start-shape prompt.
   * Used by the deprecated `create-workspace` alias, whose contract is an
   * unconditional workspace scaffold.
   */
  forceWorkspace?: boolean;
}

/**
 * Main entry for `agent-native create [name]`.
 *
 * Default behavior: scaffold a workspace at <name>/ with a multi-select
 * template picker. Use --standalone for the single-app standalone flow.
 *
 * If run *inside* an existing workspace, falls through to the add-app
 * flow that scaffolds one new app under apps/<name>/.
 */
export async function createApp(
  name?: string,
  opts?: CreateAppOptions,
): Promise<void> {
  const clack = await import("@clack/prompts");

  // Reject an invalid provided name before any interactive prompt so bad input
  // fails fast instead of blocking on the start-shape picker below.
  if (name !== undefined) {
    assertValidProjectName(name, clack);
  }

  // If we're already inside a workspace, the meaning of `create <name>` is
  // "add a new app to this workspace". Delegate to add-app.
  const workspace = detectWorkspace(process.cwd());
  if (workspace) {
    await addAppToWorkspace(name, opts);
    return;
  }

  // Standalone escape hatch — behaves like the old single-app flow.
  if (opts?.standalone) {
    await createStandaloneApp(name, opts, clack);
    return;
  }

  // When exactly one template is specified explicitly, treat it as a
  // standalone scaffold (script-friendly, matches historic behavior).
  // Use `--template a,b` or pass no --template to opt into the workspace
  // flow with the multi-select picker.
  const parsed = parseTemplateList(opts?.template);
  // Headless can't live in a workspace, so reject it when more than one
  // template is requested or when workspace semantics are forced.
  if (
    parsed.includes("headless") &&
    (parsed.length > 1 || opts?.forceWorkspace)
  ) {
    clack.cancel(
      "The headless scaffold is standalone-only. Use `agent-native create my-app --headless`, or use the Chat template when adding a UI app to a workspace.",
    );
    process.exit(1);
  }
  // A single explicit template scaffolds a standalone app, unless the caller
  // forces workspace semantics (the deprecated `create-workspace` alias), in
  // which case the template is preselected in the workspace picker below.
  if (parsed.length === 1 && !opts?.forceWorkspace) {
    await createStandaloneApp(name, opts, clack);
    return;
  }

  // No template specified: ask what shape to start from before diving into
  // "which templates?". The on-ramp choice implies the project structure, so
  // we don't ask a separate "workspace or standalone?" question — Chat and
  // Headless scaffold a single standalone app (the lightest starts; headless
  // cannot live in a workspace), while Template continues into the workspace
  // multi-select.
  if (parsed.length === 0) {
    // The deprecated `create-workspace` alias forces workspace semantics, so
    // it must skip the start-shape prompt and scaffold a workspace directly.
    if (opts?.forceWorkspace) {
      await createWorkspaceInteractive(name, opts, clack);
      return;
    }
    const shape = await promptStartShape(clack);
    if (shape === "headless" || shape === "chat") {
      await createStandaloneApp(name, { ...opts, template: shape }, clack);
      return;
    }
    // shape === "template" → full app(s) in a workspace.
    await createWorkspaceInteractive(name, opts, clack);
    return;
  }

  // Multiple explicit templates: create a workspace with them.
  await createWorkspaceInteractive(name, opts, clack);
}

/**
 * Top-level on-ramp shown by the bare `create <name>` command (no flags). The
 * choice made here implies the project structure, so we deliberately avoid a
 * separate "workspace or standalone?" question:
 *   - "template" → full app(s) in a workspace (the multi-select picker)
 *   - "chat"     → a single standalone chat UI app
 *   - "headless" → a single standalone action-first app with no UI shell
 * Chat and headless are standalone on purpose: a monorepo is unnecessary
 * ceremony for the lightest on-ramps, and headless cannot be a workspace
 * member. Either can grow into a workspace later via `add-app`.
 */
async function promptStartShape(
  clack: typeof import("@clack/prompts"),
): Promise<"template" | "chat" | "headless"> {
  const choice = await clack.select(startShapePromptOptions());
  if (clack.isCancel(choice)) {
    clack.cancel("Cancelled.");
    process.exit(0);
  }
  return choice as "template" | "chat" | "headless";
}

function startShapePromptOptions() {
  return {
    message: "How do you want to start?",
    initialValue: "chat",
    options: [
      {
        value: "chat",
        label: "Chat",
        hint: "A single app with a minimal chat UI and the browser shell wired up",
      },
      {
        value: "template",
        label: "Full template(s)",
        hint: "Clone complete apps (Mail, Calendar, Slides, ...) into a workspace",
      },
      {
        value: "headless",
        label: "Headless",
        hint: "A single action-first app with one primitive and no UI shell",
      },
    ],
  };
}

/**
 * Validate a project name supplied on the command line. Mirrors the rule in
 * `promptNameIfMissing` so an invalid name is rejected before any interactive
 * prompt runs (the sub-flows re-validate, which is a harmless no-op).
 */
function assertValidProjectName(
  name: string,
  clack: typeof import("@clack/prompts"),
): void {
  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
    clack.cancel(
      `Invalid name "${name}". Use lowercase letters, numbers, and hyphens (must start with a letter).`,
    );
    process.exit(1);
  }
}

/* ─────────────────────────────────────────────────────────────────────────
 * Workspace creation (new default)
 * ───────────────────────────────────────────────────────────────────────── */

async function createWorkspaceInteractive(
  name: string | undefined,
  opts: CreateAppOptions | undefined,
  clack: typeof import("@clack/prompts"),
): Promise<void> {
  clack.intro("Create a new agent-native workspace");

  name = await promptNameIfMissing(name, clack, "workspace", "my-platform");
  const preselected = parseTemplateList(opts?.template);

  clack.note(
    [
      `You're creating a workspace named "${name}". A workspace is a monorepo`,
      "container — it isn't an app itself. Inside it you pick one or more apps",
      "(below), and each app gets its own route, agent, and UI. Apps in the",
      "same workspace share auth, database, and the agent chat. Add more apps",
      "later with `npx @agent-native/core@latest add-app`. Chat is the UI on-ramp",
      "for a minimal chat-first app with the browser shell already wired.",
      "Dispatch is always included as the workspace control plane —",
      "it owns shared secrets, messaging, approvals, and cross-app routing.",
    ].join("\n"),
    "About workspaces",
  );

  // Dispatch is the workspace control plane (shared secrets, messaging,
  // approvals, cross-app routing) and is always scaffolded — the picker
  // only shows the optional apps. If the user explicitly passed
  // `--template=...`, those entries get unioned with dispatch.
  const optionalPicks =
    preselected.length > 0
      ? preselected.filter((t) => t !== "dispatch")
      : await promptTemplatePicker(preselected, clack, {
          defaultTemplates: ["chat"],
          preferredFirst: ["chat"],
          excludeNames: ["dispatch"],
        });
  const templates = ["dispatch", ...optionalPicks];

  const targetDir = path.resolve(process.cwd(), name);
  if (fs.existsSync(targetDir)) {
    clack.cancel(`Directory "${name}" already exists.`);
    process.exit(1);
  }

  const s = clack.spinner();
  s.start(`Scaffolding workspace "${name}"...`);
  const appNames = new Set<string>();
  const scaffoldedApps: string[] = [];

  try {
    await scaffoldWorkspaceRoot(targetDir, name);
    const workspaceCoreName = `@${name}/shared`;

    for (let i = 0; i < templates.length; i++) {
      const templateName = templates[i];
      const appName = workspaceAppNameForTemplateSelection(templateName);
      validateWorkspaceAppName(appName, clack, {
        allowDispatch: appName === "dispatch" && templateName === "dispatch",
      });
      if (appNames.has(appName)) {
        clack.cancel(
          `Workspace app "${appName}" is selected more than once. Choose unique app templates or app names.`,
        );
        process.exit(1);
      }
      appNames.add(appName);
      scaffoldedApps.push(appName);
      // Distinguish download vs local copy in the spinner so a multi-second
      // GitHub fetch doesn't look like a frozen "Scaffolding..." message.
      // Mirrors the local-vs-remote decision inside scaffoldAppTemplate.
      const willDownload =
        templateName !== "headless" && templateName.startsWith("github:")
          ? true
          : !findLocalTemplate(normalizeTemplateName(templateName));
      s.message(
        willDownload
          ? `Downloading ${titleCase(appName)} template (${i + 1}/${templates.length})...`
          : `Scaffolding ${titleCase(appName)} (${i + 1}/${templates.length})...`,
      );
      const appDir = path.join(targetDir, "apps", appName);
      await scaffoldAppTemplate(appDir, templateName);
      s.message(
        `Configuring ${titleCase(appName)} (${i + 1}/${templates.length})...`,
      );
      replacePlaceholders(appDir, appName, appTitleForScaffold(appName), name);
      rewriteTrackingAppId(appDir, appName, templateName);
      workspacifyApp({
        appDir,
        appName,
        templateName,
        workspaceRoot: targetDir,
        workspaceCoreName,
        coreDependencyVersion: getCoreDependencyVersion(),
        dispatchDependencyVersion: getDispatchDependencyVersion(),
        toolkitDependencyVersion: getToolkitDependencyVersion(),
      });
      fixPackageJsonName(appDir, appName, templateName);
      fixWebManifestName(appDir, appName, templateName);
      rewriteNetlifyToml(appDir, appName, "workspace");
      renameGitignore(appDir);
      // Each app owns its own .claude / .agents symlinks.
      setupAgentSymlinks(appDir);
    }

    s.message("Adding shared packages...");
    await scaffoldRequiredPackages(templates, targetDir);

    s.stop(
      `Workspace scaffolded with ${templates.length} app${templates.length === 1 ? "" : "s"}.`,
    );
  } catch (err: any) {
    s.stop("Failed to scaffold workspace.");
    // Remove the partially-scaffolded workspace so a retry of `agent-native
    // create <name>` doesn't trip the "Directory already exists" guard.
    cleanupOnFailure(targetDir);
    clack.cancel(err?.message ?? String(err));
    process.exit(1);
  }

  tryGitInit(targetDir);

  // Show the user the tree we just built so the workspace/app distinction is
  // visible, not just described. First-time users routinely expect their
  // workspace name to be the app — seeing apps/<template>/ subdirectories
  // makes the structure concrete.
  const treeLines = [
    `  ${name}/                    ← your workspace`,
    ...scaffoldedApps.map(
      (appName, i) =>
        `  ${i === scaffoldedApps.length - 1 ? "└─" : "├─"} apps/${appName}/`.padEnd(
          30,
        ) + `   ← app`,
    ),
  ];
  const dispatchNextStep = [
    `Once running, open Dispatch — you'll see "Workspace: ${titleCase(name)}"`,
    `at the top, with all your apps listed under it.`,
  ];

  const installSteps = hasPnpm()
    ? [
        `  pnpm install`,
        `  pnpm dev          # starts Dispatch on http://localhost:8092`,
      ]
    : [
        `  # pnpm is required but wasn't found on your PATH. Install it first:`,
        `  npm install -g pnpm`,
        ``,
        `  pnpm install`,
        `  pnpm dev          # starts Dispatch on http://localhost:8092`,
      ];

  clack.outro(
    [
      `Created workspace "${name}" with ${templates.length} app${templates.length === 1 ? "" : "s"}:`,
      ``,
      ...treeLines,
      ``,
      `Next steps:`,
      ``,
      `  cd ${name}`,
      ...installSteps,
      ``,
      ...dispatchNextStep,
      ``,
      `Add another app later:        npx @agent-native/core@latest add-app`,
      `Deploy the whole workspace:   pnpm exec agent-native deploy`,
    ].join("\n"),
  );
}

function workspaceAppNameForTemplateSelection(templateName: string): string {
  const normalized = normalizeTemplateName(templateName);
  if (!normalized.startsWith("github:")) return templateName;
  const repo = normalized.slice("github:".length).trim();
  const repoName = repo.split("/").filter(Boolean).pop() ?? "app";
  let appName = repoName
    .toLowerCase()
    .replace(/[^a-z0-9-]+/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+|-+$/g, "");
  if (!appName) appName = "app";
  if (!/^[a-z]/.test(appName)) appName = `app-${appName}`;
  return appName;
}

/**
 * Detect whether pnpm is on PATH. End-user machines often have npm/yarn but
 * not pnpm; the workspace scaffold uses pnpm workspaces, so we surface a
 * specific install hint in the outro when it's missing rather than letting
 * the user hit `zsh: command not found: pnpm`.
 */
function hasPnpm(): boolean {
  try {
    execFileSync("pnpm", ["--version"], { stdio: "ignore" });
    return true;
  } catch {
    return false;
  }
}

async function scaffoldWorkspaceRoot(
  targetDir: string,
  name: string,
): Promise<void> {
  const packageRoot = path.resolve(__dirname, "../..");
  const rootTemplate = path.join(packageRoot, "src/templates/workspace-root");
  const coreTemplate = path.join(packageRoot, "src/templates/workspace-core");

  copyDir(rootTemplate, targetDir);
  replacePlaceholders(targetDir, name, titleCase(name));
  rewriteCoreDependencyVersions(targetDir);
  renameGitignore(targetDir);

  // Inject the catalog from this repo's pnpm-workspace.yaml so templates'
  // `catalog:` version references resolve in the scaffolded workspace.
  const catalog = loadCatalog();
  if (Object.keys(catalog).length > 0) {
    const wsPath = path.join(targetDir, "pnpm-workspace.yaml");
    const existing = fs.existsSync(wsPath)
      ? fs.readFileSync(wsPath, "utf-8")
      : "";
    if (!existing.includes("catalog:")) {
      const catalogYaml = Object.entries(catalog)
        .map(([k, v]) => `  "${k}": "${v}"`)
        .join("\n");
      fs.writeFileSync(
        wsPath,
        existing.trimEnd() + "\ncatalog:\n" + catalogYaml + "\n",
      );
    }
  }

  applyLocalWorkspaceOverrides(targetDir);

  const corePackageDir = path.join(targetDir, "packages", "shared");
  fs.mkdirSync(path.join(targetDir, "packages"), { recursive: true });
  copyDir(coreTemplate, corePackageDir);
  replacePlaceholders(corePackageDir, name, titleCase(name));
  rewriteCoreDependencyVersions(corePackageDir);
  setupAgentSymlinks(corePackageDir);

  // Ensure apps/ exists (even if empty).
  fs.mkdirSync(path.join(targetDir, "apps"), { recursive: true });

  // Root-level agent instructions apply before an agent descends into an app.
  linkWorkspaceRootSkills(targetDir);
  setupAgentSymlinks(targetDir);
}

function linkWorkspaceRootSkills(targetDir: string): void {
  const sharedSkillsDir = path.join(
    targetDir,
    "packages",
    "shared",
    ".agents",
    "skills",
  );
  if (!fs.existsSync(sharedSkillsDir)) return;

  const agentsDir = path.join(targetDir, ".agents");
  const linkPath = path.join(agentsDir, "skills");
  const target = "../packages/shared/.agents/skills";

  fs.mkdirSync(agentsDir, { recursive: true });

  try {
    const stat = fs.lstatSync(linkPath);
    if (stat.isSymbolicLink()) {
      if (fs.readlinkSync(linkPath) === target) return;
      fs.unlinkSync(linkPath);
    } else {
      return;
    }
  } catch {
    // Missing link; create below.
  }

  try {
    fs.symlinkSync(
      target,
      linkPath,
      process.platform === "win32" ? "junction" : "dir",
    );
  } catch {
    try {
      copyDir(sharedSkillsDir, linkPath);
    } catch {
      // Best-effort fallback for environments that disallow symlinks.
    }
  }
}

/* ─────────────────────────────────────────────────────────────────────────
 * Adding an app into an existing workspace
 * ───────────────────────────────────────────────────────────────────────── */

/**
 * Entry for `agent-native add-app [name]`. Called from inside a workspace.
 * Shows the multi-select picker (excluding already-installed apps) and
 * scaffolds each selected template under apps/<name>/.
 *
 * When `name` is provided with `--template foo`, scaffolds exactly one app
 * named <name> using template foo (non-interactive).
 */
export async function addAppToWorkspace(
  name?: string,
  opts?: CreateAppOptions,
): Promise<void> {
  const clack = await import("@clack/prompts");
  const workspace = detectWorkspace(process.cwd());
  if (!workspace) {
    clack.cancel(
      "Not inside a workspace. Run `agent-native create` to make one first, or use `--standalone`.",
    );
    process.exit(1);
  }

  applyLocalWorkspaceOverrides(workspace.workspaceRoot);

  clack.intro("Add an app to your workspace");

  const installed = listInstalledApps(workspace.workspaceRoot);

  // Non-interactive path: name + single --template
  const preselected = parseTemplateList(opts?.template);
  if (preselected.includes("headless")) {
    clack.cancel(
      "The headless scaffold is standalone-only. Use `agent-native create my-app --headless` outside a workspace, or use the Chat template when adding a UI app to a workspace.",
    );
    process.exit(1);
  }
  if (name && preselected.length === 1) {
    const tpl = preselected[0];
    await scaffoldOneAppIntoWorkspace(workspace, name, tpl, clack);
    return;
  }

  const hasDispatch = installed.includes("dispatch");
  const templates = await promptTemplatePicker(preselected, clack, {
    excludeNames: installed,
    message: "Which apps do you want to add?",
    defaultTemplates: hasDispatch ? undefined : ["dispatch"],
    preferredFirst: hasDispatch ? ["chat"] : ["dispatch", "chat"],
    recommendedNames: hasDispatch ? [] : ["dispatch"],
  });
  if (templates.length === 0) {
    clack.cancel("No apps selected. Cancelled.");
    process.exit(0);
  }

  for (const t of templates) {
    await scaffoldOneAppIntoWorkspace(workspace, t, t, clack);
  }
}

async function scaffoldOneAppIntoWorkspace(
  workspace: { workspaceRoot: string; workspaceCoreName: string },
  appName: string,
  templateName: string,
  clack: typeof import("@clack/prompts"),
): Promise<void> {
  // Dispatch is the one reserved-route exception: the canonical workspace
  // control-plane app intentionally owns /dispatch.
  validateWorkspaceAppName(appName, clack, {
    allowDispatch: appName === "dispatch" && templateName === "dispatch",
  });
  const appsDir = path.join(workspace.workspaceRoot, "apps");
  fs.mkdirSync(appsDir, { recursive: true });
  const appDir = path.join(appsDir, appName);

  if (fs.existsSync(appDir)) {
    clack.cancel(`Directory "apps/${appName}" already exists.`);
    process.exit(1);
  }

  const s = clack.spinner();
  s.start(
    `Working... no action needed. Scaffolding apps/${appName} from ${templateName}.`,
  );

  try {
    const resolution = await scaffoldAppTemplate(appDir, templateName);
    replacePlaceholders(
      appDir,
      appName,
      appTitleForScaffold(appName),
      path.basename(workspace.workspaceRoot),
    );
    rewriteTrackingAppId(appDir, appName, templateName);
    workspacifyApp({
      appDir,
      appName,
      templateName,
      workspaceRoot: workspace.workspaceRoot,
      workspaceCoreName: workspace.workspaceCoreName,
      coreDependencyVersion: getCoreDependencyVersion(),
      dispatchDependencyVersion: getDispatchDependencyVersion(),
      toolkitDependencyVersion: getToolkitDependencyVersion(),
    });
    fixPackageJsonName(appDir, appName, templateName, {
      ...resolution,
      shape: "workspace",
    });
    fixWebManifestName(appDir, appName, templateName);
    rewriteNetlifyToml(appDir, appName, "workspace");
    renameGitignore(appDir);
    setupAgentSymlinks(appDir);
    await scaffoldRequiredPackages([templateName], workspace.workspaceRoot);
    s.stop(`Scaffolded apps/${appName}.`);
  } catch (err: any) {
    s.stop(`Failed to scaffold apps/${appName}.`);
    cleanupOnFailure(appDir);
    clack.cancel(err?.message ?? String(err));
    process.exit(1);
  }

  clack.outro(
    [
      `Done!`,
      ``,
      `  pnpm install`,
      `  pnpm dev`,
      ``,
      `The workspace gateway will detect apps/${appName} and serve it at /${appName}.`,
    ].join("\n"),
  );
}

/* ─────────────────────────────────────────────────────────────────────────
 * Standalone creation (escape hatch)
 * ───────────────────────────────────────────────────────────────────────── */

async function createStandaloneApp(
  name: string | undefined,
  opts: CreateAppOptions | undefined,
  clack: typeof import("@clack/prompts"),
): Promise<void> {
  clack.intro("Create a new standalone agent-native app");

  name = await promptNameIfMissing(name, clack, "app", "my-app");

  const targetDir = path.resolve(process.cwd(), name);
  if (fs.existsSync(targetDir)) {
    clack.cancel(`Directory "${name}" already exists.`);
    process.exit(1);
  }

  // Standalone is single-select — pick one template.
  let template =
    opts?.template && !opts.template.includes(",") ? opts.template : undefined;
  if (!template) {
    const picked = await clack.select({
      message: "Which template would you like to use?",
      options: [
        {
          value: HEADLESS_OPTION.name,
          label: HEADLESS_OPTION.label,
          hint: HEADLESS_OPTION.hint,
        },
        ...onRampFirst(coreTemplates())
          .filter((t) => t.name !== HEADLESS_OPTION.name)
          .map((t) => ({
            value: t.name,
            label: t.label,
            hint: t.hint,
          })),
      ],
    });
    if (clack.isCancel(picked)) {
      clack.cancel("Cancelled.");
      process.exit(0);
    }
    template = picked as string;
  }
  template = normalizeTemplateName(template);

  const s = clack.spinner();
  s.start(
    template === "headless"
      ? "Scaffolding the headless agent app..."
      : `Downloading the ${template} template from GitHub...`,
  );
  try {
    const resolution = await scaffoldAppTemplate(targetDir, template);
    s.message(`Setting up ${name}…`);
    postProcessStandalone(name, targetDir, template, resolution);
    s.stop("App created!");
  } catch (err: any) {
    s.stop("Failed to create app.");
    cleanupOnFailure(targetDir);
    clack.cancel(err?.message ?? String(err));
    process.exit(1);
  }

  tryGitInit(targetDir);

  if (template === "headless") {
    clack.outro(
      [
        "Done! Next steps:",
        "",
        `  cd ${name}`,
        "  pnpm install",
        "  pnpm action hello --name Builder",
        `  pnpm agent "Call hello for Builder"`,
        "",
        "Add a UI later by starting from the Chat template; `agent-native add` is reserved for integration blueprints.",
      ].join("\n"),
    );
  } else {
    clack.outro(
      `Done! Next steps:\n\n  cd ${name}\n  pnpm install\n  pnpm dev`,
    );
  }
}

/**
 * Remove a partially-scaffolded target directory after a scaffold failure so a
 * retry doesn't hit the "Directory already exists" guard. Best-effort — the
 * underlying failure is what we want surfaced, so we swallow rm errors and
 * skip if the directory is somehow already gone.
 */
function cleanupOnFailure(targetDir: string): void {
  try {
    if (fs.existsSync(targetDir)) {
      fs.rmSync(targetDir, { recursive: true, force: true });
    }
  } catch {
    // Ignore — original error is more useful than a cleanup failure.
  }
}

/* ─────────────────────────────────────────────────────────────────────────
 * Shared scaffolding helpers
 * ───────────────────────────────────────────────────────────────────────── */

/** Where a scaffolded template's bytes came from, recorded so
 *  `agent-native template sync` can reproduce them later. */
export interface ScaffoldTemplateResolution {
  templateRef?: string;
  templateSource?: "github" | "bundled" | "local-checkout";
}

export interface ScaffoldProvenance extends ScaffoldTemplateResolution {
  shape?: "workspace" | "standalone";
}

/**
 * Scaffold a single app template into `targetDir`. Resolves:
 *   - "headless" / legacy "blank" → bundled action-first template
 *   - "github:user/repo" → download the whole repo
 *   - first-party template name → use a bundled copy or download its subdir
 *     from BuilderIO/agent-native
 */
async function scaffoldAppTemplate(
  targetDir: string,
  template: string,
): Promise<ScaffoldTemplateResolution> {
  fs.mkdirSync(path.dirname(targetDir), { recursive: true });

  // Normalize legacy / renamed aliases.
  let resolved = normalizeTemplateName(template);

  if (resolved === "headless") {
    const packageRoot = path.resolve(__dirname, "../..");
    const headlessDir = path.join(packageRoot, "src/templates/headless");
    if (!fs.existsSync(headlessDir)) {
      throw new Error(
        `Headless template not found at ${headlessDir}. Is the package installed correctly?`,
      );
    }
    copyDir(headlessDir, targetDir);
    return {
      templateSource: "bundled",
      templateRef: getGitHubTemplateRefCandidates()[0],
    };
  }

  if (resolved.startsWith("github:")) {
    const repo = resolved.slice("github:".length);
    await downloadGitHubRepo(repo, targetDir);
    return {};
  }

  if (!getTemplate(resolved)) {
    throw new Error(
      `Unknown template "${template}". Known: ${allTemplateNames().join(", ")} — or use github:user/repo for community templates.`,
    );
  }

  // If running from the framework monorepo with a local templates/ dir, use
  // that. Otherwise download from GitHub. This keeps `agent-native create`
  // fast during framework development.
  const sourceTemplate = templateSourceName(resolved);
  const localTemplate = findLocalTemplate(sourceTemplate);
  if (localTemplate) {
    copyDir(localTemplate, targetDir);
    return {
      templateSource: localTemplateSourceKind(localTemplate),
      templateRef: getGitHubTemplateRefCandidates()[0],
    };
  }
  const templateRef = await downloadGitHubSubdir(
    REPO,
    `${TEMPLATES_DIR}/${sourceTemplate}`,
    targetDir,
  );
  return { templateSource: "github", templateRef };
}

/** A template dir inside the installed core package ships with the CLI;
 *  anything above it belongs to a framework checkout. */
function localTemplateSourceKind(
  localTemplate: string,
): "bundled" | "local-checkout" {
  const packageRoot = path.resolve(__dirname, "../..");
  const rel = path.relative(packageRoot, path.resolve(localTemplate));
  return rel && !rel.startsWith("..") && !path.isAbsolute(rel)
    ? "bundled"
    : "local-checkout";
}

function templateSourceName(name: string): string {
  if (name === "starter") return "chat";
  return name;
}

/**
 * Prefer a nearby templates/<name> or src/templates/<name> directory. This
 * covers the framework checkout, the dist/templates copy bundled into
 * published CLI packages, and source templates included in package files;
 * packages that do not bundle a template fall back to GitHub.
 */
function findLocalTemplate(name: string): string | undefined {
  return findLocalTemplateFrom(path.resolve(__dirname), name);
}

function findLocalTemplateFrom(
  startDir: string,
  name: string,
): string | undefined {
  let dir = path.resolve(startDir);
  for (let i = 0; i < 10; i++) {
    for (const templatesDir of ["templates", "src/templates"]) {
      const candidate = path.join(dir, templatesDir, name);
      if (fs.existsSync(path.join(candidate, "package.json"))) {
        return candidate;
      }
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return undefined;
}

function normalizeTemplateName(template: string): string {
  if (template === "blank") return "headless";
  if (template === "image" || template === "images" || template === "asset") {
    return "assets";
  }
  return template;
}

/**
 * Find a local packages/<name> directory (for framework development).
 * Returns undefined when running as a published npm package.
 */
function findLocalPackage(name: string): string | undefined {
  let dir = path.resolve(__dirname);
  for (let i = 0; i < 10; i++) {
    const candidate = path.join(dir, "packages", name);
    if (fs.existsSync(path.join(candidate, "package.json"))) {
      return candidate;
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return undefined;
}

/**
 * Pack a local framework package before linking it into a generated app.
 * Raw file: dependencies retain workspace-only catalog references, while a
 * packed artifact has the publish-ready manifest that consumers receive.
 */
function localPackageTarball(packageDir: string): string {
  const cached = localPackageTarballs.get(packageDir);
  if (cached) return cached;

  const packDir = fs.mkdtempSync(
    path.join(os.tmpdir(), "agent-native-local-package-"),
  );
  const pnpm = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
  execFileSync(pnpm, ["pack", "--pack-destination", packDir], {
    cwd: packageDir,
    encoding: "utf-8",
    env: { ...process.env, npm_config_ignore_scripts: "true" },
    stdio: "pipe",
  });

  const tarballs = fs
    .readdirSync(packDir)
    .filter((entry) => entry.endsWith(".tgz"));
  if (tarballs.length !== 1) {
    throw new Error(
      `Expected one packed local package artifact in ${packDir}, found ${tarballs.length}.`,
    );
  }

  const tarball = pathToFileURL(path.join(packDir, tarballs[0]!)).href;
  localPackageTarballs.set(packageDir, tarball);
  return tarball;
}

/**
 * Scaffold internal workspace packages required by the selected templates.
 * Deduplicates so each package is only copied once even if multiple
 * templates need it.
 */
async function scaffoldRequiredPackages(
  templateNames: string[],
  workspaceRoot: string,
): Promise<void> {
  const needed = new Set<string>();
  for (const t of templateNames) {
    const meta = getTemplate(t);
    if (meta?.requiredPackages) {
      for (const p of meta.requiredPackages) needed.add(p);
    }
  }

  for (const pkgName of needed) {
    const targetDir = path.join(workspaceRoot, "packages", pkgName);
    if (fs.existsSync(targetDir)) continue;

    fs.mkdirSync(path.join(workspaceRoot, "packages"), { recursive: true });

    const localPkg = findLocalPackage(pkgName);
    if (localPkg) {
      copyDir(localPkg, targetDir);
    } else {
      await downloadGitHubSubdir(REPO, `packages/${pkgName}`, targetDir);
    }

    // The copied package may have published framework packages as workspace:*
    // deps. Convert them to published ranges because these package-backed
    // modules are npm dependencies, not scaffolded workspace members.
    const pkgJsonPath = path.join(targetDir, "package.json");
    if (fs.existsSync(pkgJsonPath)) {
      try {
        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
        for (const depType of [
          "dependencies",
          "devDependencies",
          "peerDependencies",
        ] as const) {
          const deps = pkg[depType];
          if (!deps) continue;
          for (const [key, val] of Object.entries(deps)) {
            if (
              typeof val === "string" &&
              val.startsWith("workspace:") &&
              key === "@agent-native/core"
            ) {
              deps[key] = getCoreDependencyVersion();
            }
            if (
              typeof val === "string" &&
              val.startsWith("workspace:") &&
              key === "@agent-native/toolkit"
            ) {
              deps[key] = getToolkitDependencyVersion();
            }
          }
        }
        // These packages' `exports` maps point at `./dist/*`, and `dist/` is
        // gitignored (never committed), so a scaffolded workspace must build
        // it on install. pnpm always runs `prepare` for workspace packages,
        // unlike `postinstall`, so this is the reliable hook.
        if (
          pkg.scripts &&
          typeof pkg.scripts.build === "string" &&
          !pkg.scripts.prepare
        ) {
          pkg.scripts.prepare = "npm run build";
        }
        fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + "\n");
      } catch {}
    }
  }

  // Add a postinstall script to build workspace packages so their dist/
  // directories exist even when downloaded from GitHub (where dist/ is
  // gitignored).
  if (needed.size > 0) {
    const rootPkgPath = path.join(workspaceRoot, "package.json");
    if (fs.existsSync(rootPkgPath)) {
      try {
        const rootPkg = JSON.parse(fs.readFileSync(rootPkgPath, "utf-8"));
        rootPkg.scripts = rootPkg.scripts ?? {};
        const builds = [...needed]
          .map((n) => `pnpm --filter ./packages/${n} build`)
          .join(" && ");
        const existing = rootPkg.scripts.postinstall;
        if (existing) {
          if (!existing.includes(builds)) {
            rootPkg.scripts.postinstall = `${existing} && ${builds}`;
          }
        } else {
          rootPkg.scripts.postinstall = builds;
        }
        fs.writeFileSync(rootPkgPath, JSON.stringify(rootPkg, null, 2) + "\n");
      } catch {}
    }
  }
}

/**
 * Post-process a standalone scaffold: replace placeholders, strip
 * workspace:* deps, set up agent symlinks, etc.
 */
function postProcessStandalone(
  name: string,
  targetDir: string,
  templateName?: string,
  resolution?: ScaffoldTemplateResolution,
): void {
  const appTitle = appTitleForScaffold(name);
  replacePlaceholders(targetDir, name, appTitle);
  rewriteTrackingAppId(targetDir, name, templateName);
  rewriteAgentChatAppId(targetDir, name, templateName);
  fixPackageJsonName(targetDir, name, templateName, {
    ...resolution,
    shape: "standalone",
  });
  fixWebManifestName(targetDir, name, templateName);
  rewriteNetlifyToml(targetDir, name, "standalone");

  for (const base of ["learnings"]) {
    const defaultsFile = path.join(targetDir, `${base}.defaults.md`);
    const targetFile = path.join(targetDir, `${base}.md`);
    if (fs.existsSync(defaultsFile) && !fs.existsSync(targetFile)) {
      fs.copyFileSync(defaultsFile, targetFile);
    }
  }

  renameGitignore(targetDir);

  // No monorepo-only files to drop for standalone scaffolds.
  // DEVELOPING.md is intentionally kept: it documents local run commands,
  // DATABASE_URL defaults, and other local-run instructions that are equally
  // valid for standalone apps.

  // Resolve workspace:* and catalog: deps for standalone projects.
  // catalog: references only resolve inside a pnpm workspace with a catalog
  // defined in pnpm-workspace.yaml — standalone scaffolds don't have one.
  const catalog = loadCatalog();
  const pkgPath = path.join(targetDir, "package.json");
  if (fs.existsSync(pkgPath)) {
    try {
      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
      for (const depType of [
        "dependencies",
        "devDependencies",
        "peerDependencies",
      ] as const) {
        const deps = pkg[depType];
        if (!deps) continue;
        for (const [key, val] of Object.entries(deps)) {
          const exactOverride = STANDALONE_EXACT_DEPENDENCY_OVERRIDES[key];
          if (exactOverride) {
            deps[key] = exactOverride;
          } else if (key === "@agent-native/core") {
            deps[key] = getCoreDependencyVersion();
          } else if (key === "@agent-native/toolkit") {
            deps[key] = getToolkitDependencyVersion();
          } else if (typeof val === "string" && val.startsWith("workspace:")) {
            deps[key] = "latest";
          } else if (typeof val === "string" && val === "catalog:") {
            deps[key] = catalog[key] ?? "latest";
          }
        }
      }
      // Ensure pnpm.onlyBuiltDependencies is set so native packages
      // (better-sqlite3, esbuild, node-pty) compile their postinstall scripts
      // under pnpm 10+ without prompting for `pnpm approve-builds`.
      pkg.dependencies = pkg.dependencies ?? {};
      pkg.dependencies.postgres ??= POSTGRES_DEPENDENCY_VERSION;
      ensureReactRouterBuildDependencies(pkg);

      const requiredBuilt = ["better-sqlite3", "esbuild", "node-pty"];
      if (!pkg.pnpm || typeof pkg.pnpm !== "object") {
        pkg.pnpm = {};
      }
      const existing = Array.isArray(pkg.pnpm.onlyBuiltDependencies)
        ? pkg.pnpm.onlyBuiltDependencies
        : [];
      pkg.pnpm.onlyBuiltDependencies = Array.from(
        new Set([...existing, ...requiredBuilt]),
      );
      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
    } catch {}
  }

  // Write pnpm-workspace.yaml for pnpm v11 compatibility. pnpm v11 no longer
  // reads the pnpm field in package.json, so allowBuilds and overrides must
  // live here. Merge into any existing file (e.g. from the default template)
  // without creating duplicate section headers.
  const wsPath = path.join(targetDir, "pnpm-workspace.yaml");
  try {
    const existing = fs.existsSync(wsPath)
      ? fs.readFileSync(wsPath, "utf-8")
      : "";
    const sections: Record<string, Record<string, string>> = {
      allowBuilds: {
        "better-sqlite3": "true",
        esbuild: "true",
        "node-pty": "true",
      },
    };
    if (templateName !== "headless") {
      sections.overrides = {
        '"@assistant-ui/store"': '">=0.2.9 <0.2.14"',
        '"@assistant-ui/tap"': '"^0.5.14"',
        nf3: '"0.3.17"',
      };
    }
    const localToolkit = localToolkitOverride();
    if (localToolkit) {
      sections.overrides ??= {};
      sections.overrides['"@agent-native/toolkit"'] =
        JSON.stringify(localToolkit);
    }
    const localRecapCli = localRecapCliOverride();
    if (localRecapCli) {
      sections.overrides ??= {};
      sections.overrides['"@agent-native/recap-cli"'] =
        JSON.stringify(localRecapCli);
    }
    let updated = mergeWorkspaceYamlSections(existing, sections);
    updated = mergeWorkspaceYamlListItems(
      updated,
      "minimumReleaseAgeExclude",
      MINIMUM_RELEASE_AGE_EXCLUDES,
    );
    if (updated !== existing) {
      fs.writeFileSync(wsPath, updated);
    }
  } catch {}

  fixStandaloneTsconfig(targetDir, templateName);

  setupAgentSymlinks(targetDir);
}

function ensureReactRouterBuildDependencies(pkg: Record<string, any>): void {
  const allDeps = {
    ...pkg.dependencies,
    ...pkg.devDependencies,
    ...pkg.peerDependencies,
  };
  if (
    !allDeps["@react-router/dev"] &&
    !allDeps["react-router"] &&
    !allDeps["@react-router/fs-routes"]
  ) {
    return;
  }

  pkg.dependencies = pkg.dependencies ?? {};
  for (const key of REACT_ROUTER_BUILD_DEPENDENCIES) {
    const existing =
      pkg.dependencies[key] ??
      pkg.devDependencies?.[key] ??
      pkg.peerDependencies?.[key];
    if (!existing) continue;
    pkg.dependencies[key] =
      STANDALONE_EXACT_DEPENDENCY_OVERRIDES[key] ?? existing;
    delete pkg.devDependencies?.[key];
    delete pkg.peerDependencies?.[key];
  }
}

function fixStandaloneTsconfig(targetDir: string, templateName?: string): void {
  const tsconfigPath = path.join(targetDir, "tsconfig.json");
  if (!fs.existsSync(tsconfigPath)) return;
  try {
    const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, "utf-8")) as {
      compilerOptions?: Record<string, unknown>;
    };
    tsconfig.compilerOptions ??= {};
    const hasUiApp =
      templateName !== "headless" && fs.existsSync(path.join(targetDir, "app"));
    const paths = {
      ...((tsconfig.compilerOptions.paths as Record<string, string[]>) ?? {}),
    };
    paths["*"] ??= ["./*"];
    if (hasUiApp) {
      paths["@/*"] ??= ["./app/*"];
      paths["@shared/*"] ??= ["./shared/*"];
    }
    // baseUrl is deprecated/errors in TS 6 (TS5101/TS5102) and removed in TS 7
    // (tsc, which CI runs). paths already resolve relative to this tsconfig,
    // and the "*": ["./*"] entry replaces baseUrl's bare-specifier resolution,
    // so never emit baseUrl into scaffolds.
    delete tsconfig.compilerOptions.baseUrl;
    tsconfig.compilerOptions.paths = paths;
    fs.writeFileSync(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
  } catch {}
}

/* ─────────────────────────────────────────────────────────────────────────
 * Prompting helpers
 * ───────────────────────────────────────────────────────────────────────── */

async function promptNameIfMissing(
  name: string | undefined,
  clack: typeof import("@clack/prompts"),
  kind: "workspace" | "app",
  placeholder: string,
): Promise<string> {
  if (name) {
    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
      clack.cancel(
        `Invalid ${kind} name "${name}". Use lowercase letters, numbers, and hyphens.`,
      );
      process.exit(1);
    }
    return name;
  }
  const result = await clack.text({
    message: `What is your ${kind} name?`,
    placeholder,
    validate(value) {
      if (!value)
        return `${kind[0].toUpperCase() + kind.slice(1)} name is required`;
      if (!/^[a-z][a-z0-9-]*$/.test(value)) {
        return "Use lowercase letters, numbers, and hyphens (must start with a letter)";
      }
      if (fs.existsSync(path.resolve(process.cwd(), value))) {
        return `Directory "${value}" already exists`;
      }
    },
  });
  if (clack.isCancel(result)) {
    clack.cancel("Cancelled.");
    process.exit(0);
  }
  return result as string;
}

async function promptTemplatePicker(
  preselected: string[],
  clack: typeof import("@clack/prompts"),
  opts?: {
    defaultTemplates?: string[];
    excludeNames?: string[];
    message?: string;
    preferredFirst?: string[];
    recommendedNames?: string[];
  },
): Promise<string[]> {
  const excluded = new Set(opts?.excludeNames ?? []);
  const orderedTemplates = opts?.preferredFirst
    ? moveTemplatesToFront(coreTemplates(), opts.preferredFirst)
    : onRampFirst(coreTemplates());
  const recommendedNames = new Set(opts?.recommendedNames ?? []);
  const options = orderedTemplates
    .filter((t) => !excluded.has(t.name))
    .map((t) => ({
      value: t.name,
      label: recommendedNames.has(t.name)
        ? `${t.label} (recommended)`
        : t.label,
      hint:
        recommendedNames.has(t.name) && t.name === "dispatch"
          ? "Recommended workspace control plane: secrets, messaging, approvals, and A2A delegation"
          : t.hint,
    }));

  // If there's nothing left to pick, the caller gets an empty selection —
  // they decide how to handle it.
  if (options.length === 0) return [];

  // Default pre-selection: what the user passed via --template, falling
  // back to caller defaults, then to "chat" when available.
  const defaults =
    preselected.length > 0
      ? preselected.filter((p) => options.some((o) => o.value === p))
      : opts?.defaultTemplates
        ? opts.defaultTemplates.filter((p) =>
            options.some((o) => o.value === p),
          )
        : options.some((o) => o.value === "chat")
          ? ["chat"]
          : [];

  const baseMessage = opts?.message ?? "Which apps would you like to include?";
  const result = await clack.multiselect({
    message: `${baseMessage}\n  (↑/↓ move · space to toggle · enter to confirm)`,
    options,
    initialValues: defaults,
    required: false,
  });
  if (clack.isCancel(result)) {
    clack.cancel("Cancelled.");
    process.exit(0);
  }
  return result as string[];
}

function parseTemplateList(input?: string): string[] {
  if (!input) return [];
  return input
    .split(",")
    .map((s) => normalizeTemplateName(s.trim()))
    .filter(Boolean);
}

function listInstalledApps(workspaceRoot: string): string[] {
  const appsDir = path.join(workspaceRoot, "apps");
  if (!fs.existsSync(appsDir)) return [];
  return fs
    .readdirSync(appsDir, { withFileTypes: true })
    .filter((e) => e.isDirectory())
    .map((e) => e.name);
}

/* ─────────────────────────────────────────────────────────────────────────
 * Workspace detection
 * ───────────────────────────────────────────────────────────────────────── */

/**
 * Walk up from startDir looking for a package.json with
 * `agent-native.workspaceCore` set. Returns the workspace root and core
 * package name, or null if not inside a workspace.
 */
export function detectWorkspace(
  startDir: string,
): { workspaceRoot: string; workspaceCoreName: string } | null {
  let dir = path.resolve(startDir);
  for (let i = 0; i < 20; i++) {
    const pkgPath = path.join(dir, "package.json");
    if (fs.existsSync(pkgPath)) {
      try {
        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
        const wsCore = pkg?.["agent-native"]?.workspaceCore;
        if (typeof wsCore === "string" && wsCore.length > 0) {
          return { workspaceRoot: dir, workspaceCoreName: wsCore };
        }
      } catch {}
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return null;
}

export { parseWorkspaceScope };

/** @internal — exported for E2E tests */
export {
  scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot,
  scaffoldAppTemplate as _scaffoldAppTemplate,
  scaffoldRequiredPackages as _scaffoldRequiredPackages,
  postProcessStandalone as _postProcessStandalone,
  loadCatalog as _loadCatalog,
  fixPackageJsonName as _fixPackageJsonName,
  renameGitignore as _renameGitignore,
  rewriteNetlifyToml as _rewriteNetlifyToml,
  getCoreDependencyVersion as _getCoreDependencyVersion,
  getDispatchDependencyVersion as _getDispatchDependencyVersion,
  getToolkitDependencyVersion as _getToolkitDependencyVersion,
  getCorePackageVersion as _getCorePackageVersion,
  getGitHubTemplateRef as _getGitHubTemplateRef,
  getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates,
  githubTarballUrl as _githubTarballUrl,
  findLocalTemplateFrom as _findLocalTemplateFrom,
  workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection,
  startShapePromptOptions as _startShapePromptOptions,
  shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry,
  tarExtractArgs as _tarExtractArgs,
  downloadGitHubSubdir as _downloadGitHubSubdir,
  findLocalTemplate as _findLocalTemplate,
  templateSourceName as _templateSourceName,
  normalizeTemplateName as _normalizeTemplateName,
  appTitleForScaffold as _appTitleForScaffold,
  replacePlaceholders as _replacePlaceholders,
  rewriteTrackingAppId as _rewriteTrackingAppId,
  rewriteAgentChatAppId as _rewriteAgentChatAppId,
  fixWebManifestName as _fixWebManifestName,
  copyDir as _copyDir,
  localTemplateSourceKind as _localTemplateSourceKind,
  REPO as _REPO,
  TEMPLATES_DIR as _TEMPLATES_DIR,
};

/* ─────────────────────────────────────────────────────────────────────────
 * Download / copy helpers
 * ───────────────────────────────────────────────────────────────────────── */

function validateRepoName(repo: string): void {
  if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo)) {
    throw new ValidationError(
      `Invalid repository name "${repo}". Expected format: user/repo`,
    );
  }
}

function tarExtractArgs(
  tarPath: string,
  destDir: string,
  options: { skipAgentSymlinks?: boolean } = {},
): string[] {
  const excludes = options.skipAgentSymlinks
    ? FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES.flatMap((pattern) => [
        "--exclude",
        pattern,
      ])
    : [];
  return ["xzf", tarPath, "--strip-components=1", ...excludes, "-C", destDir];
}

function execFileBuffer(
  command: string,
  args: string[],
  options: { maxBuffer: number },
): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    execFile(
      command,
      args,
      { ...options, encoding: "buffer" },
      (error, stdout, stderr) => {
        if (error) {
          const detail = stderr?.toString().trim();
          if (detail) error.message = `${error.message}: ${detail}`;
          reject(error);
          return;
        }
        resolve(Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout));
      },
    );
  });
}

async function downloadAndExtract(
  url: string,
  destDir: string,
  options: { skipAgentSymlinks?: boolean } = {},
): Promise<void> {
  fs.mkdirSync(destDir, { recursive: true });
  // --fail-with-body so curl exits non-zero on HTTP 4xx/5xx instead of writing
  // the error body (HTML/JSON) to disk where tar then fails with the opaque
  // "Unrecognized archive format" message.
  // Keep this asynchronous: a synchronous curl blocks the event loop, which
  // makes the create command's spinner look frozen during the GitHub fetch.
  const tarball = await execFileBuffer(
    "curl",
    [
      "--fail-with-body",
      "--connect-timeout",
      "10",
      "--max-time",
      "120",
      "-sSL",
      url,
    ],
    { maxBuffer: 100 * 1024 * 1024 },
  );
  const tarPath = path.join(destDir, ".download.tar.gz");
  fs.writeFileSync(tarPath, tarball);
  try {
    execFileSync("tar", tarExtractArgs(tarPath, destDir, options), {
      stdio: "pipe",
    });
  } finally {
    fs.unlinkSync(tarPath);
  }
}

/** Resolves to the ref that actually succeeded so callers can record it. */
async function downloadGitHubSubdir(
  repo: string,
  subdir: string,
  targetDir: string,
  refOverride?: string[],
): Promise<string> {
  validateRepoName(repo);
  const refs = refOverride?.length
    ? refOverride
    : getGitHubTemplateRefCandidates();
  if (refs.length === 0) {
    throw new Error(
      "Cannot download first-party scaffold files without a versioned @agent-native/core package.",
    );
  }
  const errors: string[] = [];
  for (const ref of refs) {
    const tarUrl = githubTarballUrl(repo, ref, "tag");
    const tmpDir = path.join(
      targetDir,
      "..",
      `.agent-native-tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
    );
    try {
      await downloadAndExtract(tarUrl, tmpDir, {
        skipAgentSymlinks: repo === REPO,
      });
      const srcDir = path.join(tmpDir, subdir);
      if (!fs.existsSync(srcDir)) {
        throw new Error(
          `Template directory "${subdir}" not found at ref "${ref}".`,
        );
      }
      copyDir(srcDir, targetDir);
      return ref;
    } catch (err) {
      errors.push(
        `  ${ref}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
      );
    } finally {
      fs.rmSync(tmpDir, { recursive: true, force: true });
    }
  }
  throw new Error(
    `Failed to download templates from ${repo}. Tried refs:\n${errors.join("\n")}`,
  );
}

async function downloadGitHubRepo(
  repo: string,
  targetDir: string,
): Promise<void> {
  validateRepoName(repo);
  const tarUrl = githubTarballUrl(repo, "main", "branch");
  await downloadAndExtract(tarUrl, targetDir);
}

function githubTarballUrl(
  repo: string,
  ref: string,
  kind: "branch" | "tag",
): string {
  return `https://codeload.github.com/${repo}/tar.gz/refs/${kind === "tag" ? "tags" : "heads"}/${encodeURIComponent(ref)}`;
}

/* ─────────────────────────────────────────────────────────────────────────
 * Text / filesystem helpers
 * ───────────────────────────────────────────────────────────────────────── */

/**
 * Merge key-value entries into named sections of a pnpm-workspace.yaml string
 * without creating duplicate section headers. For each section:
 *   - If the section already exists, new entries are injected after its header.
 *   - If the section is absent, a new block is appended at the end.
 * Entries already present (by key) are skipped.
 */
function mergeWorkspaceYamlSections(
  yaml: string,
  sections: Record<string, Record<string, string>>,
): string {
  let result = yaml;
  for (const [section, entries] of Object.entries(sections)) {
    for (const [key, value] of Object.entries(entries)) {
      if (result.includes(key)) continue;
      const sectionHeader = new RegExp(`^${section}:\\s*$`, "m");
      const match = sectionHeader.exec(result);
      if (match) {
        const insertAt = match.index + match[0].length;
        result =
          result.slice(0, insertAt) +
          `\n  ${key}: ${value}` +
          result.slice(insertAt);
      } else {
        result =
          result.trimEnd() +
          (result ? "\n" : "") +
          `\n${section}:\n  ${key}: ${value}\n`;
      }
    }
  }
  return result;
}

function mergeWorkspaceYamlListItems(
  yaml: string,
  section: string,
  items: string[],
): string {
  let result = yaml;
  for (const item of items) {
    const rendered = `  - ${item}`;
    if (result.includes(rendered)) continue;
    const sectionHeader = new RegExp(`^${section}:\\s*$`, "m");
    const match = sectionHeader.exec(result);
    if (match) {
      const insertAt = match.index + match[0].length;
      result =
        result.slice(0, insertAt) + `\n${rendered}` + result.slice(insertAt);
    } else {
      result =
        result.trimEnd() +
        (result ? "\n" : "") +
        `\n${section}:\n${rendered}\n`;
    }
  }
  return result;
}

/**
 * Load the pnpm workspace catalog.
 * First tries the build-time snapshot at dist/catalog.json (works when
 * running as a published npm package). Falls back to parsing the monorepo
 * pnpm-workspace.yaml (works during local framework development).
 */
function loadCatalog(): Record<string, string> {
  try {
    // Build-time snapshot generated by finalize-build.mjs
    const snapshotPath = path.resolve(__dirname, "../catalog.json");
    if (fs.existsSync(snapshotPath)) {
      return JSON.parse(fs.readFileSync(snapshotPath, "utf-8"));
    }

    // Fallback: parse pnpm-workspace.yaml from the monorepo root
    // From dist/cli/ or src/cli/: 4 levels up → packages/core → packages → repo root
    const repoRoot = path.resolve(__dirname, "../../../..");
    const wsPath = path.join(repoRoot, "pnpm-workspace.yaml");
    if (!fs.existsSync(wsPath)) return {};
    const content = fs.readFileSync(wsPath, "utf-8");
    const result: Record<string, string> = {};
    let inCatalog = false;
    for (const line of content.split("\n")) {
      if (/^catalog:\s*$/.test(line)) {
        inCatalog = true;
        continue;
      }
      if (inCatalog) {
        if (/^\S/.test(line)) break;
        const match = line.match(/^\s+"?([^":]+)"?\s*:\s*"?([^"]+)"?\s*$/);
        if (match) result[match[1]] = match[2];
      }
    }
    return result;
  } catch {
    return {};
  }
}

function titleCase(name: string): string {
  return name
    .split("-")
    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
    .join(" ");
}

function appTitleForScaffold(appName: string): string {
  return titleCase(appName);
}

function isChatOnRampTemplate(templateName: string | undefined): boolean {
  return templateName === "chat" || templateName === "starter";
}

function trackingTemplateName(
  templateName: string | undefined,
): string | undefined {
  return templateName === "starter" ? "chat" : templateName;
}

function defaultPackageDescriptionForScaffold(appName: string): string {
  const appTitle = appTitleForScaffold(appName);
  return `Workspace app for ${appTitle}.`;
}

function shouldReplaceScaffoldDescription(value: unknown): boolean {
  if (typeof value !== "string" || !value.trim()) return true;
  return /\b(starter|new app|blank\b.*\bapp)\b/i.test(value);
}

function fixPackageJsonName(
  appDir: string,
  name: string,
  templateName?: string,
  provenance?: ScaffoldProvenance,
): void {
  const pkgPath = path.join(appDir, "package.json");
  if (!fs.existsSync(pkgPath)) return;
  try {
    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
    pkg.name = name;
    const appTitle = appTitleForScaffold(name);
    // When the user picked a custom name (e.g. `add-app todo --template=chat`)
    // the template's displayName would otherwise leak into the workspace apps
    // grid as the new app's label. Overwrite it so the app shows up as "Todo"
    // instead of the source template's branding.
    if (templateName && name !== templateName) {
      pkg.displayName = appTitle;
    }
    if (
      shouldReplaceScaffoldDescription(pkg.description) ||
      (isChatOnRampTemplate(templateName) && name !== templateName)
    ) {
      pkg.description = defaultPackageDescriptionForScaffold(name);
    }
    const scaffoldGuidance = scaffoldGuidanceForTemplate(templateName);
    if (scaffoldGuidance) {
      const agentNative =
        pkg["agent-native"] &&
        typeof pkg["agent-native"] === "object" &&
        !Array.isArray(pkg["agent-native"])
          ? pkg["agent-native"]
          : {};
      const coreVersion = getCorePackageVersion();
      agentNative.scaffold = {
        template: trackingTemplateName(templateName),
        frameworkSkills: scaffoldGuidance,
        ...(provenance?.templateRef
          ? { templateRef: provenance.templateRef }
          : {}),
        ...(provenance?.templateSource
          ? { templateSource: provenance.templateSource }
          : {}),
        ...(coreVersion ? { coreVersion } : {}),
        ...(provenance?.shape ? { shape: provenance.shape } : {}),
      };
      pkg["agent-native"] = agentNative;
    }
    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
  } catch {}
}

function scaffoldGuidanceForTemplate(
  templateName: string | undefined,
): "default" | "headless" | undefined {
  if (!templateName || templateName.startsWith("github:")) return undefined;
  const normalized = normalizeTemplateName(templateName);
  if (normalized === "headless") return "headless";
  return getTemplate(normalized) ? "default" : undefined;
}

function fixWebManifestName(
  appDir: string,
  name: string,
  templateName?: string,
): void {
  if (!isChatOnRampTemplate(templateName) || name === templateName) return;
  const manifestPath = path.join(appDir, "public", "manifest.json");
  if (!fs.existsSync(manifestPath)) return;
  try {
    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
    const appTitle = titleCase(name);
    manifest.name = appTitle;
    manifest.short_name = appTitle;
    if (
      typeof manifest.description !== "string" ||
      /\b(blank app|starter|chat-first)\b/i.test(manifest.description)
    ) {
      manifest.description = defaultPackageDescriptionForScaffold(name);
    }
    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
  } catch {}
}

function getCoreDependencyVersion(): string {
  if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE === "1") {
    const localCore = findLocalPackage("core");
    if (localCore) return localPackageTarball(localCore);
  }

  // Pin to the exact core version running this CLI rather than the npm
  // `latest` dist-tag. `latest` can drift forward after `create` runs (a
  // stale/cached CLI invocation, or simply time passing before `npm
  // install`), installing a newer core release whose internal toolkit
  // dependency no longer matches the toolkit range this CLI just wrote into
  // the scaffold via getOwnPackageDependencyVersion() — reintroducing the
  // exact duplicate/mismatched-toolkit class of bug this pinning exists to
  // prevent. For the common case — `npx @agent-native/core@<version> create`
  // against the public registry — this exact version is guaranteed
  // installable, since npx just fetched it. Private/offline mirrors with a
  // retention window narrower than "every historical version" are a known
  // gap; `getCorePackageVersion()` returning undefined (e.g. malformed own
  // package.json) falls back to `latest` rather than failing scaffolding
  // outright. Local file deps stay opt-in so scaffolded repos remain
  // portable by default.
  return getCorePackageVersion() ?? "latest";
}

function getDispatchDependencyVersion(): string {
  if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE === "1") {
    const localDispatch = findLocalPackage("dispatch");
    if (localDispatch) return pathToFileURL(localDispatch).href;
  }

  // Unlike toolkit, core's own package.json does not declare
  // @agent-native/dispatch as a dependency, so there is no published
  // compatible range to read here — "latest" is the best available signal.
  return "latest";
}

function getToolkitDependencyVersion(): string {
  if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE === "1") {
    const localToolkit = findLocalPackage("toolkit");
    if (localToolkit) return localPackageTarball(localToolkit);
  }

  return getOwnPackageDependencyVersion("@agent-native/toolkit");
}

/**
 * Toolkit is versioned and published independently of core, so its npm
 * `latest` dist-tag can briefly point to an incompatible release relative to
 * the core version currently running this CLI. The published core
 * `package.json` already carries the exact compatible range changesets
 * resolved at release time — read it from there instead of trusting
 * `latest`, which is only safe for pinning `core` itself.
 */
function getOwnPackageDependencyVersion(depName: string): string {
  try {
    const ownPkgPath = path.join(__dirname, "../../package.json");
    const ownPkg = JSON.parse(fs.readFileSync(ownPkgPath, "utf-8"));
    const range = ownPkg.dependencies?.[depName];
    const isPublishedRange =
      typeof range === "string" &&
      range.length > 0 &&
      !range.startsWith("workspace:") &&
      range !== "catalog:";
    if (isPublishedRange) return range;
  } catch {}

  return "latest";
}

function localToolkitOverride(): string | null {
  if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE !== "1") return null;
  const localToolkit = findLocalPackage("toolkit");
  return localToolkit ? localPackageTarball(localToolkit) : null;
}

function localRecapCliOverride(): string | null {
  if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE !== "1") return null;
  const localRecapCli = findLocalPackage("recap-cli");
  return localRecapCli ? pathToFileURL(localRecapCli).href : null;
}

function applyLocalWorkspaceOverrides(targetDir: string): void {
  const localToolkit = localToolkitOverride();
  const localRecapCli = localRecapCliOverride();
  if (!localToolkit && !localRecapCli) return;

  const wsPath = path.join(targetDir, "pnpm-workspace.yaml");
  const existing = fs.existsSync(wsPath)
    ? fs.readFileSync(wsPath, "utf-8")
    : "";
  const updated = mergeWorkspaceYamlSections(existing, {
    overrides: {
      ...(localToolkit
        ? { '"@agent-native/toolkit"': JSON.stringify(localToolkit) }
        : {}),
      ...(localRecapCli
        ? { '"@agent-native/recap-cli"': JSON.stringify(localRecapCli) }
        : {}),
    },
  });
  if (updated !== existing) fs.writeFileSync(wsPath, updated);
}

function getCorePackageVersion(): string | undefined {
  try {
    const packageRoot = path.resolve(__dirname, "../..");
    const pkg = JSON.parse(
      fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"),
    );
    return typeof pkg.version === "string" ? pkg.version : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Git refs to try, in priority order, when downloading templates from the
 * framework repo. The release tag scheme has shifted over time:
 *
 *   - ≤ 0.7.83: single repo-wide tag `v<version>` (legacy).
 *   - ≥ 0.8.0:  changesets per-package tags
 *               `@agent-native/core@<version>` (current).
 *
 * Published CLIs intentionally use only immutable version tags. Falling back
 * to mutable `main` can copy a template that imports exports not present in
 * the installed core package, leaving a generated app broken at SSR startup.
 * Local framework development uses the checkout's templates and packages
 * before this downloader runs, so it does not need a mutable fallback.
 */
function getGitHubTemplateRefCandidates(): string[] {
  const version = getCorePackageVersion();
  const candidates: string[] = [];
  if (version && /^\d+\.\d+\.\d+(?:-.+)?$/.test(version)) {
    candidates.push(`@agent-native/core@${version}`);
    candidates.push(`v${version}`);
  }
  return candidates;
}

/** @deprecated Kept for backward-compatible test imports. Returns the
 *  highest-priority candidate; callers that need the full fallback list
 *  should use `getGitHubTemplateRefCandidates()`. */
function getGitHubTemplateRef(): string {
  return getGitHubTemplateRefCandidates()[0]!;
}

function rewriteCoreDependencyVersions(projectDir: string): void {
  const pkgPath = path.join(projectDir, "package.json");
  if (!fs.existsSync(pkgPath)) return;
  try {
    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
    for (const depType of [
      "dependencies",
      "devDependencies",
      "peerDependencies",
    ] as const) {
      const deps = pkg[depType];
      if (deps?.["@agent-native/core"]) {
        deps["@agent-native/core"] = getCoreDependencyVersion();
      }
      if (deps?.["@agent-native/toolkit"]) {
        deps["@agent-native/toolkit"] = getToolkitDependencyVersion();
      }
    }
    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
  } catch {}
}

function validateWorkspaceAppName(
  appName: string,
  clack: typeof import("@clack/prompts"),
  opts?: { allowDispatch?: boolean },
): void {
  const error =
    opts?.allowDispatch && appName === "dispatch"
      ? null
      : getWorkspaceAppIdValidationError(appName);
  if (error) {
    clack.cancel(error);
    process.exit(1);
  }
}

function upsertTomlBuildEnvironment(
  content: string,
  vars: Record<string, string>,
): string {
  const lines = content.split("\n");
  const sectionIndex = lines.findIndex(
    (line) => line.trim() === "[build.environment]",
  );
  if (sectionIndex === -1) {
    const envLines = ["", "[build.environment]"].concat(
      Object.entries(vars).map(([key, value]) => `  ${key} = "${value}"`),
    );
    return content.trimEnd() + "\n" + envLines.join("\n") + "\n";
  }

  let nextSectionIndex = lines.findIndex(
    (line, index) => index > sectionIndex && /^\s*\[/.test(line),
  );
  if (nextSectionIndex === -1) nextSectionIndex = lines.length;

  for (const [key, value] of Object.entries(vars)) {
    const existingIndex = lines.findIndex(
      (line, index) =>
        index > sectionIndex &&
        index < nextSectionIndex &&
        new RegExp(`^\\s*${key}\\s*=`).test(line),
    );
    const nextLine = `  ${key} = "${value}"`;
    if (existingIndex === -1) {
      lines.splice(nextSectionIndex, 0, nextLine);
      nextSectionIndex += 1;
    } else {
      lines[existingIndex] = nextLine;
    }
  }

  return lines.join("\n");
}

function ensureRedirect(
  content: string,
  from: string,
  to: string,
  status: number,
): string {
  const escapedFrom = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  const redirectPattern = new RegExp(
    `\\n?\\[\\[redirects\\]\\]\\s+from\\s*=\\s*"${escapedFrom}"\\s+to\\s*=\\s*"[^"]*"\\s+status\\s*=\\s*\\d+(?:\\s+force\\s*=\\s*(?:true|false))?`,
    "m",
  );
  const block = [
    "",
    "[[redirects]]",
    `  from = "${from}"`,
    `  to = "${to}"`,
    `  status = ${status}`,
  ].join("\n");
  if (redirectPattern.test(content)) {
    return content.replace(redirectPattern, block);
  }
  return content.trimEnd() + "\n" + block + "\n";
}

function removeRedirect(content: string, from: string): string {
  const escapedFrom = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  const redirectPattern = new RegExp(
    `\\n?\\[\\[redirects\\]\\]\\s+from\\s*=\\s*"${escapedFrom}"\\s+to\\s*=\\s*"[^"]*"\\s+status\\s*=\\s*\\d+(?:\\s+force\\s*=\\s*(?:true|false))?`,
    "gm",
  );
  return content.replace(redirectPattern, "").replace(/\n{3,}/g, "\n\n");
}

function addWorkspaceMountNetlifyConfig(
  content: string,
  appName: string,
): string {
  const basePath = `/${appName}`;
  let next = upsertTomlBuildEnvironment(content, {
    APP_BASE_PATH: basePath,
    VITE_APP_BASE_PATH: basePath,
    NITRO_PRESET: "netlify",
    NPM_CONFIG_PRODUCTION: "false",
  });

  if (appName === "dispatch") {
    next = ensureRedirect(next, "/", "/dispatch/overview", 302);
    next = ensureRedirect(next, "/dispatch", "/dispatch/overview", 302);
    for (const [from, to] of DISPATCH_WORKSPACE_ROOT_REDIRECTS) {
      next = ensureRedirect(next, `/${from}`, `/dispatch/${to}`, 302);
    }
    next = removeRedirect(next, "/dispatch/*");
  }

  return next;
}

function rewriteNetlifyToml(
  appDir: string,
  appName: string,
  mode: "standalone" | "workspace",
): void {
  const netlifyPath = path.join(appDir, "netlify.toml");
  if (!fs.existsSync(netlifyPath)) return;

  try {
    let content = fs.readFileSync(netlifyPath, "utf-8");
    const originalCommand = content.match(/^\s*command = "([^"]*)"$/m)?.[1];
    const usesUnpooledDatabase =
      originalCommand?.includes("NETLIFY_DATABASE_URL_UNPOOLED") ?? false;
    const buildCommand =
      mode === "workspace"
        ? `APP_BASE_PATH=/${appName} VITE_APP_BASE_PATH=/${appName} NITRO_PRESET=netlify pnpm --filter ${appName} build`
        : "NITRO_PRESET=netlify pnpm build";
    const databaseSetup =
      'export DATABASE_URL=\\"${NETLIFY_DATABASE_URL:-$DATABASE_URL}\\"';
    const buildDatabasePrefix = usesUnpooledDatabase
      ? 'DATABASE_URL=\\"${NETLIFY_DATABASE_URL_UNPOOLED:-$DATABASE_URL}\\" '
      : "";
    const command = `${databaseSetup} && ${buildDatabasePrefix}${buildCommand}`;
    const publishPath = mode === "workspace" ? `apps/${appName}/dist` : "dist";
    const functionsPath =
      mode === "workspace"
        ? `apps/${appName}/.netlify/functions-internal`
        : ".netlify/functions-internal";

    content = content
      .replace(/^(\s*)command = ".*"$/m, `$1command = "${command}"`)
      .replace(
        /publish = "templates\/[^"]+\/dist"/g,
        `publish = "${publishPath}"`,
      )
      .replace(
        /functions = "templates\/[^"]+\/\.netlify\/functions-internal"/g,
        `functions = "${functionsPath}"`,
      )
      // Strip the `ignore` script line: it references a monorepo script path
      // (scripts/netlify-ignore-build.mjs) that doesn't exist in scaffolds, so
      // skip-unchanged would never work and every deploy logs a not-found error.
      .replace(/^\s*ignore\s*=\s*"[^"]*"\s*\n/m, "");

    if (mode === "workspace") {
      content = addWorkspaceMountNetlifyConfig(content, appName);
    }

    fs.writeFileSync(netlifyPath, content);
  } catch {}
}

function rewriteAgentChatAppId(
  appDir: string,
  appName: string,
  templateName?: string,
): void {
  const pluginPath = path.join(appDir, "server", "plugins", "agent-chat.ts");
  if (!fs.existsSync(pluginPath)) return;

  try {
    const content = fs.readFileSync(pluginPath, "utf-8");
    const sourceAppIds = ["chat", "starter"];
    if (templateName && templateName !== appName) {
      sourceAppIds.push(templateName);
    }
    const pattern = new RegExp(
      `(appId:\\s*)(["'])(${sourceAppIds.map(escapeRegExp).join("|")})\\2`,
    );
    if (!pattern.test(content)) return;

    const next = content.replace(
      pattern,
      (_match, prefix: string, quote: string) =>
        `${prefix}${quote}${appName}${quote}`,
    );
    if (next !== content) {
      fs.writeFileSync(pluginPath, next);
    }
  } catch {}
}

function rewriteTrackingAppId(
  appDir: string,
  appName: string,
  templateName?: string,
): void {
  const rootPath = path.join(appDir, "app", "root.tsx");
  if (!fs.existsSync(rootPath)) return;

  try {
    const content = fs.readFileSync(rootPath, "utf-8");
    const trackedTemplateName = trackingTemplateName(templateName);
    const sourceAppIds = ["agent-native-[^\"']+", "\\{\\{APP_NAME\\}\\}"];
    if (templateName && templateName !== appName) {
      sourceAppIds.push(escapeRegExp(templateName));
    }
    if (isChatOnRampTemplate(templateName)) {
      sourceAppIds.push("starter", "chat");
    }
    const pattern = new RegExp(
      `(^\\s*app:\\s*)(["'])(?:${sourceAppIds.join("|")})\\2(\\s*,?)`,
      "m",
    );
    if (!pattern.test(content)) return;

    let next = content.replace(
      pattern,
      (_match, prefix: string, quote: string, suffix: string) =>
        `${prefix}${quote}${appName}${quote}${suffix}`,
    );

    if (
      trackedTemplateName &&
      trackedTemplateName !== appName &&
      !hasTrackingTemplate(next)
    ) {
      next = next.replace(
        /(^\s*app:\s*["'][^"']+["'],?\s*$)/m,
        (line) =>
          `${line}\n    template: ${JSON.stringify(trackedTemplateName)},`,
      );
    }

    if (next !== content) {
      fs.writeFileSync(rootPath, next);
    }
  } catch {}
}

function escapeRegExp(value: string): string {
  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

function hasTrackingTemplate(content: string): boolean {
  const match = content.match(/configureTracking\(\{[\s\S]*?\}\);/);
  return !!match && /^\s*template\s*:/m.test(match[0]);
}

function tryGitInit(dir: string): boolean {
  try {
    execFileSync("git", ["init"], { cwd: dir, stdio: "pipe" });
    execFileSync("git", ["add", "-A"], { cwd: dir, stdio: "pipe" });
    execFileSync(
      "git",
      ["commit", "-m", "Initial commit from agent-native create"],
      {
        cwd: dir,
        stdio: "pipe",
        env: {
          ...process.env,
          GIT_AUTHOR_NAME: "agent-native",
          GIT_AUTHOR_EMAIL: "noreply@agent-native.com",
          GIT_COMMITTER_NAME: "agent-native",
          GIT_COMMITTER_EMAIL: "noreply@agent-native.com",
        },
      },
    );
    return true;
  } catch {
    return false;
  }
}

function renameGitignore(dir: string): void {
  const src = path.join(dir, "_gitignore");
  const dst = path.join(dir, ".gitignore");
  if (fs.existsSync(src)) fs.renameSync(src, dst);
}

function replacePlaceholders(
  dir: string,
  appName: string,
  appTitle: string,
  workspaceName?: string,
): void {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const p = path.join(dir, entry.name);
    if (entry.isSymbolicLink()) continue;
    if (entry.isDirectory()) {
      replacePlaceholders(p, appName, appTitle, workspaceName);
      continue;
    }
    let content: string;
    try {
      content = fs.readFileSync(p, "utf-8");
    } catch {
      continue;
    }
    const hasWs =
      workspaceName !== undefined && content.includes("{{WORKSPACE_NAME}}");
    if (
      !content.includes("{{APP_NAME}}") &&
      !content.includes("{{APP_TITLE}}") &&
      !hasWs
    ) {
      continue;
    }
    let next = content;
    if (workspaceName !== undefined) {
      next = next.replace(/\{\{WORKSPACE_NAME\}\}/g, workspaceName);
    }
    next = next
      .replace(/\{\{APP_NAME\}\}/g, appName)
      .replace(/\{\{APP_TITLE\}\}/g, appTitle);
    fs.writeFileSync(p, next);
  }
}

function copyDir(src: string, dest: string, root?: string): void {
  const resolvedRoot = root ?? path.resolve(src);
  fs.mkdirSync(dest, { recursive: true });
  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
    const srcPath = path.join(src, entry.name);
    if (shouldSkipScaffoldEntry(entry.name, srcPath)) continue;
    const destPath = path.join(dest, entry.name);
    if (entry.isSymbolicLink()) {
      const target = fs.readlinkSync(srcPath);
      const resolvedTarget = path.resolve(path.dirname(srcPath), target);
      if (resolvedTarget.startsWith(resolvedRoot)) {
        fs.symlinkSync(target, destPath);
      } else {
        try {
          const stat = fs.statSync(srcPath);
          if (stat.isDirectory()) {
            copyDir(srcPath, destPath, resolvedRoot);
          } else {
            fs.copyFileSync(srcPath, destPath);
          }
        } catch {
          // Broken symlink — skip silently
        }
      }
    } else if (entry.isDirectory()) {
      copyDir(srcPath, destPath, resolvedRoot);
    } else {
      fs.copyFileSync(srcPath, destPath);
    }
  }
}

function shouldSkipScaffoldEntry(name: string, srcPath?: string): boolean {
  const pathParts = srcPath?.split(path.sep);
  if (
    name === "plans" &&
    pathParts?.at(-2) === "plan" &&
    pathParts.at(-3) === "templates"
  ) {
    return true;
  }
  if (name === "preview.html" && srcPath?.split(path.sep).includes("plans")) {
    return true;
  }
  if (
    /^settings(?:\..*)?\.json$/.test(name) &&
    srcPath?.split(path.sep).includes(".claude")
  ) {
    return true;
  }
  // `.generated/bridge` is committed source, not a build artifact: the design
  // app imports it at module load, so skipping it yields a workspace that 500s
  // on every page. Everything else under `.generated` is regenerated at dev time.
  if (pathParts?.at(-2) === ".generated") {
    return name !== "bridge";
  }
  if (
    name === ".generated" &&
    srcPath &&
    fs.existsSync(path.join(srcPath, "bridge"))
  ) {
    return false;
  }
  if (
    name === "node_modules" ||
    name === ".agent-native" ||
    name === ".env" ||
    name === ".env.local" ||
    name === "pnpm-lock.yaml" ||
    name === ".netlify" ||
    name === ".vercel" ||
    name === ".generated" ||
    name === ".react-router" ||
    name === ".output" ||
    name === "build" ||
    name === "dist" ||
    name === "test-results" ||
    name === "playwright-report" ||
    name === ".DS_Store"
  ) {
    return true;
  }
  return name.endsWith(".tmp.json") || /\.db(?:-shm|-wal)?$/.test(name);
}