/**
 * Plan helper commands.
 *
 * The `plan local` commands are intentionally separate from the Plan app
 * actions. They do not call MCP, hosted write actions, SQLite, or hosted
 * storage; they only read local files or serve them from a localhost bridge so
 * privacy-focused users have an auditable no-DB path. The top-level
 * `plan blocks` command is a schema-only, no-auth helper for fetching the
 * public block catalog before authoring local MDX; it never sends plan content.
 */

import { spawnSync } from "node:child_process";
import crypto from "node:crypto";
import fs from "node:fs";
import http, {
  type IncomingMessage,
  type Server,
  type ServerResponse,
} from "node:http";
import path from "node:path";
import { pathToFileURL } from "node:url";

import {
  DEFAULT_PLAN_APP_URL,
  defaultPlanBlocksOut,
  fetchPlanBlockCatalog,
  normalizePlanBlockFormat,
  planActionEndpoint,
} from "./plan-blocks.js";

type LocalPlanKind = "plan" | "recap";

type LocalPlanFiles = {
  dir: string;
  planMdx: string;
  canvasMdx?: string;
  prototypeMdx?: string;
  stateJson?: string;
  assets?: Record<string, string>;
};

export type LocalPlanValidationIssue = {
  file: string;
  line: number;
  message: string;
};

type LocalPlanPreviewInput = {
  dir: string;
  kind?: LocalPlanKind;
  title?: string;
  brief?: string;
  appUrl?: string;
};

type LocalPlanPreviewResult = {
  ok: true;
  dir: string;
  out?: string;
  url: string;
  title: string;
  kind: LocalPlanKind;
  files: string[];
  opened?: boolean;
  openCommand?: string;
  openError?: string;
};

type LocalPlanBridgeMdxFolder = {
  "plan.mdx": string;
  "canvas.mdx"?: string;
  "prototype.mdx"?: string;
  ".plan-state.json"?: string;
  "assets/"?: Record<string, string>;
};

type LocalPlanBridgeComment = {
  id: string;
  planId: string;
  parentCommentId: string | null;
  sectionId: string | null;
  kind: string;
  status: string;
  anchor: string | null;
  message: string;
  createdBy: string;
  authorEmail: string | null;
  authorName: string | null;
  resolutionTarget: string | null;
  mentions: unknown[];
  mentionsJson: string | null;
  resolvedBy: string | null;
  resolvedAt: string | null;
  consumedAt: string | null;
  deletedAt: string | null;
  deletedBy: string | null;
  createdAt: string;
  updatedAt: string;
};

type LocalPlanBridgeCommentInput = {
  id?: string;
  parentCommentId?: string | null;
  sectionId?: string | null;
  kind?: string;
  status?: string;
  anchor?: string | null;
  message?: string;
  createdBy?: string;
  authorEmail?: string | null;
  authorName?: string | null;
  resolutionTarget?: string | null;
  mentions?: unknown[];
  resolvedBy?: string | null;
  resolvedAt?: string | null;
};

type LocalPlanBridgeCommentUpdate = {
  comments?: LocalPlanBridgeCommentInput[];
  deletedCommentIds?: string[];
};

type VisualAnswerSourcePayload = {
  question?: string;
  title?: string;
  brief?: string;
  repoPath?: string;
  sourceUrl?: string;
  sourceType?: string;
  mdx: {
    "plan.mdx": string;
    "canvas.mdx"?: string;
    "prototype.mdx"?: string;
    "assets/"?: Record<string, string>;
  };
};

export type PublishVisualAnswerInput = {
  appUrl: string;
  token: string;
  question?: string;
  sourcePath?: string;
  out?: string;
  prevPlanId?: string;
  repo?: string;
  sourceUrl?: string;
  sourceType?: string;
  visibility?: "private" | "org" | "public";
  fetchFn?: typeof fetch;
  cwd?: string;
};

export type LocalPlanBridgePayload = {
  ok: true;
  version: 1;
  source: "agent-native-local-bridge";
  localOnly: true;
  slug: string;
  dir: string;
  title: string;
  brief: string;
  kind: LocalPlanKind;
  updatedAt: string;
  files: string[];
  mdx: LocalPlanBridgeMdxFolder;
  comments: LocalPlanBridgeComment[];
};

export type LocalPlanServeResult = {
  ok: true;
  dir: string;
  url: string;
  urlFile?: string;
  bridgeUrl: string;
  appUrl: string;
  title: string;
  kind: LocalPlanKind;
  files: string[];
  host: string;
  port: number;
  opened?: boolean;
  openCommand?: string;
  openError?: string;
};

export type LocalPlanBridgeServer = {
  server: Server;
  result: LocalPlanServeResult;
};

export type RendererValidationIssue = {
  path: string;
  message: string;
};

export type RendererValidation = {
  /** Whether a loopback renderer validate endpoint was reachable and answered. */
  ran: boolean;
  endpoint: string;
  /** Renderer verdict — present only when `ran` is true. */
  valid?: boolean;
  issues?: RendererValidationIssue[];
  /** Transport/endpoint error when `ran` is false (unreachable, 404, old deploy). */
  error?: string;
};

export type LocalPlanVerifyResult = {
  ok: boolean;
  dir: string;
  url: string;
  urlFile?: string;
  bridgeUrl: string;
  appUrl: string;
  title: string;
  kind: LocalPlanKind;
  files: string[];
  preflight: {
    status: number;
    allowOrigin: string | null;
    allowPrivateNetwork: string | null;
  };
  bridge: {
    status: number;
    ok: boolean;
    source?: string;
    localOnly?: boolean;
    files?: string[];
    mdxFiles?: string[];
    error?: string;
  };
  validation: RendererValidation;
  warnings: string[];
};

type OpenLocalUrlResult = {
  ok: boolean;
  command: string;
  error?: string;
};

const LOCAL_PLAN_COMMENTS_FILE = "comments.json";
const LOCAL_PLAN_OWNER_EMAIL = "local@agent-native.local";
const LOCAL_PLAN_BRIDGE_COMMENT_BODY_LIMIT = 1024 * 1024;

const LOCAL_PLAN_ASSET_MAX_SINGLE_BYTES = 2 * 1024 * 1024;
const LOCAL_PLAN_ASSET_MAX_TOTAL_BYTES = 10 * 1024 * 1024;
const AGENT_NATIVE_MANIFEST_FILE = "agent-native.json";
const VISUAL_ANSWER_SOURCE_FILENAME = "visual-answer-source.json";
const VISUAL_ANSWER_URL_FILENAME = "visual-answer-url.txt";
const PLAN_ACTION_HTTP_TIMEOUT_MS = 45_000;
const LOCAL_PLAN_ASSET_EXTENSIONS = new Set([
  "png",
  "jpg",
  "jpeg",
  "gif",
  "webp",
  "svg",
]);

function parseArgs(argv: string[]): Record<string, string | boolean> {
  const out: Record<string, string | boolean> = {};
  for (let i = 0; i < argv.length; i += 1) {
    const token = argv[i];
    if (!token.startsWith("--")) continue;
    const key = token.slice(2);
    const next = argv[i + 1];
    if (next === undefined || next.startsWith("--")) out[key] = true;
    else {
      out[key] = next;
      i += 1;
    }
  }
  return out;
}

function stringArg(
  args: Record<string, string | boolean>,
  key: string,
): string {
  const value = args[key];
  if (typeof value !== "string" || value.length === 0) {
    throw new Error(`Missing --${key}`);
  }
  return value;
}

function optionalArg(
  args: Record<string, string | boolean>,
  key: string,
): string | undefined {
  const value = args[key];
  return typeof value === "string" && value.length > 0 ? value : undefined;
}

function boolArg(args: Record<string, string | boolean>, key: string): boolean {
  return args[key] === true;
}

function sanitizeHttpDetail(value: string, maxLength: number): string {
  const normalized = value.replace(/\s+/g, " ").trim();
  if (normalized.length <= maxLength) return normalized;
  return `${normalized.slice(0, maxLength - 3)}...`;
}

function normalizeVisibility(
  value: string | undefined,
): "private" | "org" | "public" | undefined {
  if (!value) return undefined;
  if (value === "private" || value === "org" || value === "public") {
    return value;
  }
  throw new Error(
    `Invalid --visibility "${value}" (expected private, org, or public)`,
  );
}

function normalizeVisualAnswerSourceType(value: string | undefined): string {
  if (!value) return "code";
  if (
    [
      "code",
      "pull-request",
      "commit",
      "branch",
      "diff",
      "issue",
      "page",
    ].includes(value)
  ) {
    return value;
  }
  throw new Error(
    `Invalid --source-type "${value}" (expected code, pull-request, commit, branch, diff, issue, or page)`,
  );
}

function visualAnswerUrlFromPublishResult(
  result: unknown,
  appUrl: string,
): string | null {
  const base = appUrl.replace(/\/$/, "");
  if (!result || typeof result !== "object") return null;
  const record = result as Record<string, unknown>;
  const rawUrl =
    typeof record.url === "string"
      ? record.url
      : record.path && typeof record.path === "string"
        ? record.path
        : null;
  if (rawUrl) {
    try {
      return new URL(rawUrl, `${base}/`).toString();
    } catch {
      return null;
    }
  }
  const planId =
    typeof record.planId === "string"
      ? record.planId
      : record.plan &&
          typeof record.plan === "object" &&
          typeof (record.plan as Record<string, unknown>).id === "string"
        ? ((record.plan as Record<string, unknown>).id as string)
        : null;
  return planId ? `${base}/plans/${encodeURIComponent(planId)}` : null;
}

async function fetchActionWithTimeout(
  url: string,
  init: RequestInit,
  fetchFn: typeof fetch,
): Promise<Response> {
  return await fetchFn(url, {
    ...init,
    signal: init.signal ?? AbortSignal.timeout(PLAN_ACTION_HTTP_TIMEOUT_MS),
  });
}

export function localPlanFolderName(title: string): string {
  const slug = title
    .normalize("NFKD")
    .replace(/[\u0300-\u036f]/g, "")
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 64)
    .replace(/-+$/g, "");
  return slug || "untitled-plan";
}

function normalizeKind(value: string | undefined): LocalPlanKind {
  if (!value) return "plan";
  if (value === "plan" || value === "recap") return value;
  throw new Error(`Invalid --kind "${value}" (expected plan or recap)`);
}

function normalizeSlash(filePath: string): string {
  return filePath.replace(/\\/g, "/");
}

function normalizeRelativePath(filePath: string): string | null {
  if (!filePath.trim() || path.isAbsolute(filePath)) return null;
  const normalized = path.posix
    .normalize(normalizeSlash(filePath.trim()))
    .replace(/\/+$/, "");
  if (
    !normalized ||
    normalized === "." ||
    normalized === ".." ||
    normalized.startsWith("../") ||
    normalized.split("/").some((part) => !part || part === "." || part === "..")
  ) {
    return null;
  }
  return normalized;
}

function findUpward(startDir: string, filename: string): string | null {
  let current = path.resolve(startDir);
  for (;;) {
    const candidate = path.join(current, filename);
    if (fs.existsSync(candidate)) return candidate;
    const parent = path.dirname(current);
    if (parent === current) return null;
    current = parent;
  }
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return !!value && typeof value === "object" && !Array.isArray(value);
}

function manifestRootPath(value: unknown): string | null {
  if (typeof value === "string") return normalizeRelativePath(value);
  if (isRecord(value) && typeof value.path === "string") {
    return normalizeRelativePath(value.path);
  }
  return null;
}

function planManifestConfig(): { rootDir: string; plansPath: string } | null {
  const configuredManifest =
    process.env.AGENT_NATIVE_MANIFEST?.trim() ||
    process.env.AGENT_NATIVE_MANIFEST_PATH?.trim();
  const manifestPath = configuredManifest
    ? path.resolve(configuredManifest)
    : findUpward(process.cwd(), AGENT_NATIVE_MANIFEST_FILE);
  if (!manifestPath) return null;

  try {
    const parsed = JSON.parse(
      fs.readFileSync(manifestPath, "utf-8"),
    ) as unknown;
    const apps = isRecord(parsed) && isRecord(parsed.apps) ? parsed.apps : null;
    const planApp = apps && isRecord(apps.plan) ? apps.plan : null;
    const roots = planApp && Array.isArray(planApp.roots) ? planApp.roots : [];
    const plansPath = roots
      .map(manifestRootPath)
      .find((item): item is string => Boolean(item));
    return plansPath
      ? { rootDir: path.dirname(manifestPath), plansPath }
      : null;
  } catch {
    return null;
  }
}

function localPlanWorkspaceRoot(startDir = process.cwd()): string {
  const manifestPath = findUpward(startDir, AGENT_NATIVE_MANIFEST_FILE);
  if (manifestPath) return path.dirname(manifestPath);
  const gitDir = findUpward(startDir, ".git");
  if (gitDir) return path.dirname(gitDir);

  const configuredManifest =
    process.env.AGENT_NATIVE_MANIFEST?.trim() ||
    process.env.AGENT_NATIVE_MANIFEST_PATH?.trim();
  if (configuredManifest) return path.dirname(path.resolve(configuredManifest));
  return process.cwd();
}

function defaultPlansDir(): string {
  const configured = process.env.PLAN_LOCAL_DIR;
  if (configured?.trim()) return path.resolve(configured.trim());
  const manifest = planManifestConfig();
  if (manifest) return path.resolve(manifest.rootDir, manifest.plansPath);
  return path.resolve("plans");
}

function defaultLocalPlanAppUrl(): string {
  return (
    process.env.PLAN_LOCAL_APP_URL ||
    process.env.PLAN_BASE_URL ||
    "http://localhost:8096"
  );
}

function defaultLocalPlanBridgeAppUrl(): string {
  return (
    process.env.PLAN_LOCAL_BRIDGE_APP_URL ||
    process.env.PLAN_BASE_URL ||
    DEFAULT_PLAN_APP_URL
  );
}

function normalizeAppUrl(value: string | undefined): string {
  return (value || defaultLocalPlanAppUrl()).replace(/\/+$/, "");
}

function normalizeBridgeAppUrl(value: string | undefined): string {
  return (value || defaultLocalPlanBridgeAppUrl()).replace(/\/+$/, "");
}

function localPlanPreviewUrl(dir: string, appUrl?: string): string {
  const base = `${normalizeAppUrl(appUrl)}/local-plans/${encodeURIComponent(
    path.basename(path.resolve(dir)),
  )}`;
  const repoPath = repoRelativePlanPath(dir);
  if (!repoPath) return base;
  return `${base}?${new URLSearchParams({ path: repoPath }).toString()}`;
}

function realpathIfExists(filePath: string): string {
  try {
    return fs.realpathSync.native(filePath);
  } catch {
    return path.resolve(filePath);
  }
}

function repoRelativePlanPath(dir: string): string | null {
  const resolved = realpathIfExists(dir);
  const root = realpathIfExists(localPlanWorkspaceRoot(resolved));
  const relative = path.relative(root, resolved);
  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
    return null;
  }
  return normalizeSlash(relative);
}

function localPlanBridgePageUrl(input: {
  dir: string;
  bridgeUrl: string;
  appUrl?: string;
}): string {
  // Keep the real local folder name out of the hosted request path. The bridge
  // payload supplies the actual slug after the browser connects on loopback.
  // The opaque id keeps simultaneous bridge sessions distinct without
  // disclosing the folder name or access token to the hosted request.
  const bridgeId = crypto
    .createHash("sha256")
    .update(input.bridgeUrl)
    .digest("hex")
    .slice(0, 16);
  return `${normalizeBridgeAppUrl(input.appUrl)}/local-plans/local-${bridgeId}#bridge=${encodeURIComponent(
    input.bridgeUrl,
  )}`;
}

function writeLocalPlanUrlFile(dir: string, url: string, urlFile?: string) {
  const file = path.resolve(urlFile || path.join(dir, ".plan-url"));
  fs.writeFileSync(file, `${url}\n`, { encoding: "utf-8", mode: 0o600 });
  return file;
}

function runOpenCommand(command: string, args: string[]): OpenLocalUrlResult {
  const result = spawnSync(command, args, {
    stdio: "ignore",
    windowsHide: true,
  });
  const commandDisplay = [command, ...args].join(" ");
  if (result.error) {
    return {
      ok: false,
      command: commandDisplay,
      error: result.error.message,
    };
  }
  if (typeof result.status === "number" && result.status !== 0) {
    return {
      ok: false,
      command: commandDisplay,
      error: `exit code ${result.status}`,
    };
  }
  return { ok: true, command: commandDisplay };
}

function openLocalUrl(url: string): OpenLocalUrlResult {
  const platform = process.platform;
  if (platform === "darwin") {
    for (const appName of [
      "Google Chrome",
      "Chromium",
      "Microsoft Edge",
      "Brave Browser",
    ]) {
      const result = runOpenCommand("open", ["-a", appName, url]);
      if (result.ok) return result;
    }
    return runOpenCommand("open", [url]);
  }
  if (platform === "win32") {
    return runOpenCommand("cmd", ["/c", "start", "", url]);
  }
  return runOpenCommand("xdg-open", [url]);
}

function escapeHtml(value: string): string {
  return value
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#39;");
}

function stripFrontmatter(source: string): {
  body: string;
  frontmatter: Record<string, string>;
} {
  if (!source.startsWith("---\n")) return { body: source, frontmatter: {} };
  const end = source.indexOf("\n---", 4);
  if (end < 0) return { body: source, frontmatter: {} };
  const frontmatterSource = source.slice(4, end).trim();
  const body = source.slice(end + 4).replace(/^\r?\n/, "");
  const frontmatter: Record<string, string> = {};
  for (const line of frontmatterSource.split(/\r?\n/)) {
    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
    if (!match) continue;
    const value = match[2]
      .trim()
      .replace(/^['"]|['"]$/g, "")
      .trim();
    frontmatter[match[1]] = value;
  }
  return { body, frontmatter };
}

function firstHeading(source: string): string | null {
  for (const line of source.split(/\r?\n/)) {
    const match = line.match(/^#{1,3}\s+(.+)$/);
    if (match) return match[1].trim();
  }
  return null;
}

function splitMdxBlocks(source: string): Array<{
  type: "markdown" | "component";
  name?: string;
  value: string;
}> {
  const blocks: Array<{
    type: "markdown" | "component";
    name?: string;
    value: string;
  }> = [];
  const lines = source.split(/\r?\n/);
  let markdown: string[] = [];
  let component: string[] | null = null;
  let componentName = "";

  function flushMarkdown() {
    const value = markdown.join("\n").trim();
    if (value) blocks.push({ type: "markdown", value });
    markdown = [];
  }

  function flushComponent() {
    if (!component) return;
    blocks.push({
      type: "component",
      name: componentName || "MDX component",
      value: component.join("\n").trim(),
    });
    component = null;
    componentName = "";
  }

  for (const line of lines) {
    const start = line.match(/^<([A-Z][A-Za-z0-9_]*)\b/);
    if (!component && start) {
      flushMarkdown();
      component = [line];
      componentName = start[1];
      if (/\/>\s*$/.test(line)) flushComponent();
      continue;
    }

    if (component) {
      component.push(line);
      if (new RegExp(`</${componentName}>\\s*$`).test(line)) {
        flushComponent();
      }
      continue;
    }

    markdown.push(line);
  }

  flushComponent();
  flushMarkdown();
  return blocks;
}

function renderMarkdownish(source: string): string {
  const lines = source.split(/\r?\n/);
  const html: string[] = [];
  let inCode = false;
  let codeLines: string[] = [];
  let listLines: string[] = [];

  function flushList() {
    if (listLines.length === 0) return;
    html.push(
      `<ul>${listLines.map((line) => `<li>${escapeHtml(line)}</li>`).join("")}</ul>`,
    );
    listLines = [];
  }

  function flushCode() {
    if (!inCode) return;
    html.push(`<pre><code>${escapeHtml(codeLines.join("\n"))}</code></pre>`);
    codeLines = [];
    inCode = false;
  }

  for (const line of lines) {
    if (line.startsWith("```")) {
      if (inCode) flushCode();
      else {
        flushList();
        inCode = true;
        codeLines = [];
      }
      continue;
    }
    if (inCode) {
      codeLines.push(line);
      continue;
    }

    const heading = line.match(/^(#{1,4})\s+(.+)$/);
    if (heading) {
      flushList();
      const level = Math.min(heading[1].length, 4);
      html.push(`<h${level}>${escapeHtml(heading[2].trim())}</h${level}>`);
      continue;
    }

    const bullet = line.match(/^\s*[-*]\s+(.+)$/);
    if (bullet) {
      listLines.push(bullet[1]);
      continue;
    }

    if (!line.trim()) {
      flushList();
      continue;
    }

    flushList();
    html.push(`<p>${escapeHtml(line.trim())}</p>`);
  }

  flushCode();
  flushList();
  return html.join("\n");
}

function readLocalPlanAssets(dir: string): Record<string, string> | undefined {
  const assetsDir = path.join(dir, "assets");
  if (!fs.existsSync(assetsDir)) return undefined;

  const assets: Record<string, string> = {};
  let totalBytes = 0;
  for (const entry of fs.readdirSync(assetsDir, { withFileTypes: true })) {
    if (!entry.isFile()) continue;
    const filename = path.basename(entry.name);
    if (!filename || filename !== entry.name) continue;
    const ext = filename.split(".").pop()?.toLowerCase() ?? "";
    if (!LOCAL_PLAN_ASSET_EXTENSIONS.has(ext)) continue;

    const abs = path.join(assetsDir, filename);
    const bytes = fs.readFileSync(abs);
    if (bytes.byteLength > LOCAL_PLAN_ASSET_MAX_SINGLE_BYTES) continue;
    if (totalBytes + bytes.byteLength > LOCAL_PLAN_ASSET_MAX_TOTAL_BYTES) {
      continue;
    }
    totalBytes += bytes.byteLength;
    assets[filename] = bytes.toString("base64");
  }

  return Object.keys(assets).length > 0 ? assets : undefined;
}

export function readLocalPlanFiles(dir: string): LocalPlanFiles {
  const resolved = path.resolve(dir);
  const planPath = path.join(resolved, "plan.mdx");
  if (!fs.existsSync(planPath)) {
    throw new Error(`Missing local plan source: ${planPath}`);
  }
  const readOptional = (file: string) => {
    const abs = path.join(resolved, file);
    return fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : undefined;
  };
  return {
    dir: resolved,
    planMdx: fs.readFileSync(planPath, "utf-8"),
    canvasMdx: readOptional("canvas.mdx"),
    prototypeMdx: readOptional("prototype.mdx"),
    stateJson: readOptional(".plan-state.json"),
    assets: readLocalPlanAssets(resolved),
  };
}

function localPlanMdxFolder(files: LocalPlanFiles): LocalPlanBridgeMdxFolder {
  return {
    "plan.mdx": files.planMdx,
    ...(files.canvasMdx ? { "canvas.mdx": files.canvasMdx } : {}),
    ...(files.prototypeMdx ? { "prototype.mdx": files.prototypeMdx } : {}),
    ...(files.stateJson ? { ".plan-state.json": files.stateJson } : {}),
    ...(files.assets ? { "assets/": files.assets } : {}),
  };
}

function localPlanFileList(files: LocalPlanFiles): string[] {
  return [
    "plan.mdx",
    ...(files.canvasMdx ? ["canvas.mdx"] : []),
    ...(files.prototypeMdx ? ["prototype.mdx"] : []),
    ...(files.stateJson ? [".plan-state.json"] : []),
    ...Object.keys(files.assets ?? {}).map((filename) => `assets/${filename}`),
  ];
}

function localPlanSourceEntries(files: LocalPlanFiles): Array<{
  file: string;
  source: string;
}> {
  return [
    { file: "plan.mdx", source: files.planMdx },
    ...(files.canvasMdx
      ? [{ file: "canvas.mdx", source: files.canvasMdx }]
      : []),
    ...(files.prototypeMdx
      ? [{ file: "prototype.mdx", source: files.prototypeMdx }]
      : []),
  ];
}

function lineNumberAt(source: string, index: number): number {
  let line = 1;
  for (let i = 0; i < index; i += 1) {
    if (source.charCodeAt(i) === 10) line += 1;
  }
  return line;
}

function maskFencedCode(source: string): string {
  return source.replace(
    /(^|\n)(```|~~~)[\s\S]*?(\n\2[^\n]*(?=\n|$))/g,
    (match) => match.replace(/[^\n]/g, " "),
  );
}

function findJsxOpeningTagEnd(source: string, start: number): number {
  let quote: string | null = null;
  let braceDepth = 0;
  for (let i = start; i < source.length; i += 1) {
    const char = source[i];
    if (quote) {
      if (char === "\\" && i + 1 < source.length) {
        i += 1;
        continue;
      }
      if (char === quote) quote = null;
      continue;
    }
    if (char === '"' || char === "'" || char === "`") {
      quote = char;
      continue;
    }
    if (char === "{") {
      braceDepth += 1;
      continue;
    }
    if (char === "}") {
      braceDepth = Math.max(0, braceDepth - 1);
      continue;
    }
    if (char === ">" && braceDepth === 0) return i;
  }
  return -1;
}

function addValidationIssue(
  issues: LocalPlanValidationIssue[],
  file: string,
  source: string,
  index: number,
  message: string,
) {
  issues.push({ file, line: lineNumberAt(source, index), message });
}

const ENTITY_RE = /&(?:[a-z][a-z0-9]+|#[0-9]+|#x[0-9a-f]+);/gi;
const HTML_TEXT_ATTR_RE =
  /\b(?:aria-label|alt|placeholder|title|value)=\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/gi;
const WIREFRAME_TEXT_ATTR_RE =
  /\b(?:text|value|label|placeholder|title|note|due)=\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/gi;

function normalizeVisibleText(value: string): string {
  return value
    .replace(/&nbsp;|&#160;|&#x0*a0;/gi, " ")
    .replace(ENTITY_RE, "x")
    .replace(/\s+/g, " ")
    .trim();
}

function meaningfulTextLength(value: string | undefined): number {
  return normalizeVisibleText(value ?? "").length;
}

function htmlMeaningfulTextLength(html: string): number {
  let length = 0;
  for (const match of html.matchAll(HTML_TEXT_ATTR_RE)) {
    length += meaningfulTextLength(match[1] ?? match[2] ?? match[3]);
  }

  const visibleText = html
    .replace(/<!--[\s\S]*?-->/g, " ")
    .replace(/<script\b[\s\S]*?<\/script>/gi, " ")
    .replace(/<style\b[\s\S]*?<\/style>/gi, " ")
    .replace(/<[^>]+>/g, " ");
  length += meaningfulTextLength(visibleText);

  return length;
}

function hasSkeletonGeometry(html: string): boolean {
  return (
    /<(?:div|span|section|main|article|ul|li)\b/i.test(html) &&
    /\b(?:height|width|background|border|padding|wf-card|wf-box|wf-pill|wf-chip)\b/i.test(
      html,
    )
  );
}

function stringAttributeValues(source: string, name: string): string[] {
  const values: string[] = [];
  const re = new RegExp(
    `\\b${name}\\s*=\\s*(?:\\{\\s*\`([\\s\\S]*?)\`\\s*\\}|\\{\\s*"([^"]*)"\\s*\\}|\\{\\s*'([^']*)'\\s*\\}|"([^"]*)"|'([^']*)')`,
    "g",
  );
  for (const match of source.matchAll(re)) {
    const value = match[1] ?? match[2] ?? match[3] ?? match[4] ?? match[5];
    if (value !== undefined) values.push(value);
  }
  return values;
}

function hasUnparsedAttributeExpression(source: string, name: string): boolean {
  return new RegExp(`\\b${name}\\s*=\\s*\\{`).test(source);
}

function hasMeaningfulWireframeHtml(screenOpening: string): boolean | null {
  const htmlValues = stringAttributeValues(screenOpening, "html");
  if (htmlValues.length === 0) {
    return hasUnparsedAttributeExpression(screenOpening, "html") ? null : false;
  }
  return htmlValues.some(
    (html) => htmlMeaningfulTextLength(html) >= 2 || hasSkeletonGeometry(html),
  );
}

function hasMeaningfulKitScreen(screenSource: string): boolean {
  for (const match of screenSource.matchAll(WIREFRAME_TEXT_ATTR_RE)) {
    if (meaningfulTextLength(match[1] ?? match[2] ?? match[3]) >= 2) {
      return true;
    }
  }
  if (/\bitems\s*=\s*\{[\s\S]*?\blabel\s*:/i.test(screenSource)) return true;
  if (/\brows\s*=\s*\{[\s\S]*?\b[klv]\s*:/i.test(screenSource)) return true;
  return false;
}

function hasMeaningfulWireframeScreen(blockSource: string): boolean | null {
  const screenMatch = /<Screen\b/.exec(blockSource);
  if (!screenMatch) return false;
  const screenStart = screenMatch.index;
  const screenOpeningEnd = findJsxOpeningTagEnd(blockSource, screenStart);
  if (screenOpeningEnd < 0) return false;
  const screenOpening = blockSource.slice(screenStart, screenOpeningEnd + 1);
  const htmlMeaningful = hasMeaningfulWireframeHtml(screenOpening);
  if (htmlMeaningful === true) return true;

  const selfClosing = /\/\s*>$/.test(screenOpening);
  const closeIndex = selfClosing
    ? -1
    : blockSource.indexOf("</Screen>", screenOpeningEnd + 1);
  const screenSource =
    closeIndex >= 0
      ? blockSource.slice(screenStart, closeIndex + "</Screen>".length)
      : screenOpening;
  if (hasMeaningfulKitScreen(screenSource)) return true;

  return htmlMeaningful === null ? null : false;
}

function lintWireframeBlocks(
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const scanSource = maskFencedCode(source);
  const re = /<WireframeBlock\b/g;
  let match: RegExpExecArray | null;
  while ((match = re.exec(scanSource))) {
    const start = match.index;
    const openingEnd = findJsxOpeningTagEnd(scanSource, start);
    if (openingEnd < 0) {
      addValidationIssue(
        issues,
        file,
        source,
        start,
        "WireframeBlock opening tag is not closed.",
      );
      continue;
    }

    const opening = scanSource.slice(start, openingEnd + 1);
    const unsupportedAttr = opening.match(
      /\b(data|screens|screen|elements)\s*=/,
    );
    if (unsupportedAttr) {
      addValidationIssue(
        issues,
        file,
        source,
        start,
        `WireframeBlock uses unsupported "${unsupportedAttr[1]}" prop. Put content inside a <Screen> child instead.`,
      );
    }

    const selfClosing = /\/\s*>$/.test(opening);
    const closeTag = "</WireframeBlock>";
    const closeIndex = selfClosing
      ? -1
      : scanSource.indexOf(closeTag, openingEnd + 1);
    const blockSource = selfClosing
      ? opening
      : closeIndex >= 0
        ? scanSource.slice(start, closeIndex + closeTag.length)
        : scanSource.slice(start, openingEnd + 1);

    if (!selfClosing && closeIndex < 0) {
      addValidationIssue(
        issues,
        file,
        source,
        start,
        "WireframeBlock must have a closing </WireframeBlock> tag.",
      );
    }

    if (selfClosing || !/<Screen\b/.test(blockSource)) {
      addValidationIssue(
        issues,
        file,
        source,
        start,
        'WireframeBlock must wrap a <Screen> child; self-closing wireframes render empty. Use <WireframeBlock><Screen surface="browser">...</Screen></WireframeBlock>.',
      );
      continue;
    }

    const meaningfulScreen = hasMeaningfulWireframeScreen(blockSource);
    if (meaningfulScreen === false) {
      addValidationIssue(
        issues,
        file,
        source,
        start,
        'WireframeBlock contains an empty <Screen>; local previews render blank wireframes. Add visible html text/controls or kit nodes such as <Title text="Checkout" /> and <Btn label="Pay" />.',
      );
    }
  }
}

function lintColumnsBlocks(
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const scanSource = maskFencedCode(source);
  const re = /<Columns\b/g;
  let match: RegExpExecArray | null;
  while ((match = re.exec(scanSource))) {
    const start = match.index;
    const openingEnd = findJsxOpeningTagEnd(scanSource, start);
    if (openingEnd < 0) continue;
    const opening = source.slice(start, openingEnd + 1);
    const columnsAttr = readJsxAttribute(opening, "columns");
    if (!columnsAttr) continue;
    const entries =
      columnsAttr.kind === "expression"
        ? extractTopLevelObjectLiterals(columnsAttr.value)
        : null;
    if (entries && entries.length > 0) continue;
    addValidationIssue(
      issues,
      file,
      source,
      start,
      'Columns must use <Column> children or a columns={[{ id, label, blocks }]} array, not a bare columns= prop. Use <Columns><Column label="Before">...</Column><Column label="After">...</Column></Columns>.',
    );
  }
}

type JsxAttributeValue = {
  name: string;
  kind: "expression" | "string" | "bare" | "boolean";
  value: string;
  start: number;
};

function findBalancedEnd(
  source: string,
  start: number,
  open: string,
  close: string,
): number {
  let depth = 0;
  let quote: string | null = null;
  for (let i = start; i < source.length; i += 1) {
    const char = source[i];
    if (quote) {
      if (char === "\\" && i + 1 < source.length) {
        i += 1;
        continue;
      }
      if (char === quote) quote = null;
      continue;
    }
    if (char === '"' || char === "'" || char === "`") {
      quote = char;
      continue;
    }
    if (char === open) {
      depth += 1;
      continue;
    }
    if (char === close) {
      depth -= 1;
      if (depth === 0) return i;
    }
  }
  return -1;
}

function readJsxAttribute(
  opening: string,
  name: string,
): JsxAttributeValue | null {
  let i = 0;
  while (i < opening.length) {
    if (!/[A-Za-z_:]/.test(opening[i] ?? "")) {
      i += 1;
      continue;
    }
    const nameStart = i;
    i += 1;
    while (/[\w:.-]/.test(opening[i] ?? "")) i += 1;
    const attrName = opening.slice(nameStart, i);
    while (/\s/.test(opening[i] ?? "")) i += 1;
    if (opening[i] !== "=") {
      if (attrName === name) {
        return { name, kind: "boolean", value: "true", start: nameStart };
      }
      continue;
    }
    i += 1;
    while (/\s/.test(opening[i] ?? "")) i += 1;
    const valueStart = i;
    const quote = opening[i];
    if (quote === '"' || quote === "'" || quote === "`") {
      i += 1;
      while (i < opening.length) {
        if (opening[i] === "\\" && i + 1 < opening.length) {
          i += 2;
          continue;
        }
        if (opening[i] === quote) break;
        i += 1;
      }
      const value = opening.slice(valueStart + 1, i);
      i += 1;
      if (attrName === name) {
        return { name, kind: "string", value, start: valueStart + 1 };
      }
      continue;
    }
    if (quote === "{") {
      const end = findBalancedEnd(opening, i, "{", "}");
      if (end < 0) {
        if (attrName === name) {
          return {
            name,
            kind: "expression",
            value: opening.slice(valueStart + 1),
            start: valueStart + 1,
          };
        }
        break;
      }
      const value = opening.slice(valueStart + 1, end);
      i = end + 1;
      if (attrName === name) {
        return { name, kind: "expression", value, start: valueStart + 1 };
      }
      continue;
    }
    while (i < opening.length && !/[\s>]/.test(opening[i] ?? "")) i += 1;
    if (attrName === name) {
      return {
        name,
        kind: "bare",
        value: opening.slice(valueStart, i),
        start: valueStart,
      };
    }
  }
  return null;
}

function expressionOffset(expression: string): number {
  return expression.search(/\S/);
}

function extractTopLevelObjectLiterals(expression: string): Array<{
  source: string;
  start: number;
}> | null {
  const leading = expressionOffset(expression);
  if (leading < 0 || expression[leading] !== "[") return null;
  const arrayEnd = findBalancedEnd(expression, leading, "[", "]");
  if (arrayEnd < 0) return null;
  const objects: Array<{ source: string; start: number }> = [];
  let i = leading + 1;
  while (i < arrayEnd) {
    const char = expression[i];
    if (/\s|,/.test(char ?? "")) {
      i += 1;
      continue;
    }
    if (char !== "{") {
      return null;
    }
    const objectEnd = findBalancedEnd(expression, i, "{", "}");
    if (objectEnd < 0 || objectEnd > arrayEnd) return null;
    objects.push({
      source: expression.slice(i, objectEnd + 1),
      start: i,
    });
    i = objectEnd + 1;
  }
  return objects;
}

function findValueEnd(source: string, start: number): number {
  let i = start;
  let quote: string | null = null;
  let depth = 0;
  while (i < source.length) {
    const char = source[i];
    if (quote) {
      if (char === "\\" && i + 1 < source.length) {
        i += 2;
        continue;
      }
      if (char === quote) quote = null;
      i += 1;
      continue;
    }
    if (char === '"' || char === "'" || char === "`") {
      quote = char;
      i += 1;
      continue;
    }
    if (char === "{" || char === "[" || char === "(") {
      depth += 1;
      i += 1;
      continue;
    }
    if (char === "}" || char === "]" || char === ")") {
      if (depth === 0) return i;
      depth -= 1;
      i += 1;
      continue;
    }
    if (char === "," && depth === 0) return i;
    i += 1;
  }
  return source.length;
}

function readObjectKey(
  source: string,
  start: number,
): {
  key: string;
  keyStart: number;
  colon: number;
} | null {
  let i = start;
  while (/\s|,/.test(source[i] ?? "")) i += 1;
  const keyStart = i;
  const quote = source[i];
  let key = "";
  if (quote === '"' || quote === "'") {
    i += 1;
    const valueStart = i;
    while (i < source.length) {
      if (source[i] === "\\" && i + 1 < source.length) {
        i += 2;
        continue;
      }
      if (source[i] === quote) break;
      i += 1;
    }
    key = source.slice(valueStart, i);
    i += 1;
  } else if (/[A-Za-z_$]/.test(quote ?? "")) {
    i += 1;
    while (/[\w$]/.test(source[i] ?? "")) i += 1;
    key = source.slice(keyStart, i);
  } else {
    return null;
  }
  while (/\s/.test(source[i] ?? "")) i += 1;
  if (source[i] !== ":") return null;
  return { key, keyStart, colon: i };
}

function readTopLevelObjectProperty(
  objectSource: string,
  name: string,
): { value: string; valueStart: number } | null {
  const body = objectSource.trim().startsWith("{")
    ? objectSource.slice(1, objectSource.lastIndexOf("}"))
    : objectSource;
  let i = 0;
  while (i < body.length) {
    const key = readObjectKey(body, i);
    if (!key) {
      i += 1;
      continue;
    }
    const valueStart = key.colon + 1;
    const valueEnd = findValueEnd(body, valueStart);
    if (key.key === name) {
      return { value: body.slice(valueStart, valueEnd), valueStart };
    }
    i = valueEnd + 1;
  }
  return null;
}

function isStaticNonEmptyStringLiteral(value: string): boolean {
  const trimmed = value.trim();
  const quote = trimmed[0];
  if (quote !== '"' && quote !== "'" && quote !== "`") return false;
  if (!trimmed.endsWith(quote)) return false;
  if (quote === "`" && /\$\{/.test(trimmed)) return false;
  return trimmed.slice(1, -1).trim().length > 0;
}

function hasRequiredStaticString(objectSource: string, name: string): boolean {
  const prop = readTopLevelObjectProperty(objectSource, name);
  return prop ? isStaticNonEmptyStringLiteral(prop.value) : false;
}

function hasRequiredStaticId(objectSource: string): boolean {
  return hasRequiredStaticString(objectSource, "id");
}

function hasRequiredEnumLiteral(
  objectSource: string,
  name: string,
  allowed: readonly string[],
): boolean {
  const prop = readTopLevelObjectProperty(objectSource, name);
  if (!prop) return false;
  const trimmed = prop.value.trim();
  const quote = trimmed[0];
  if (quote !== '"' && quote !== "'" && quote !== "`") return false;
  if (!trimmed.endsWith(quote)) return false;
  if (quote === "`" && /\$\{/.test(trimmed)) return false;
  return allowed.includes(trimmed.slice(1, -1).trim());
}

// Shared per-item checks so the top-level `<Checklist items={[…]} />` tag and
// blocks authored as JSON inside a container's `tabs={[…]}` / `columns={[…]}`
// array enforce the SAME required fields. `listBase` is the absolute offset of
// the items array in the original source so line numbers point near the item.
function checkChecklistItemList(
  items: Array<{ source: string; start: number }>,
  listBase: number,
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  items.forEach((item, index) => {
    const base = listBase + item.start;
    if (!hasRequiredStaticId(item.source)) {
      addValidationIssue(
        issues,
        file,
        source,
        base,
        `Checklist items[${index}].id is required by the Plan renderer schema; add a stable string id.`,
      );
    }
    if (!hasRequiredStaticString(item.source, "label")) {
      addValidationIssue(
        issues,
        file,
        source,
        base,
        `Checklist items[${index}].label is required by the Plan renderer schema; add a non-empty string label.`,
      );
    }
  });
}

function checkQuestionObjectList(
  questionObjects: Array<{ source: string; start: number }>,
  listBase: number,
  tag: string,
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  questionObjects.forEach((question, questionIndex) => {
    const questionBase = listBase + question.start;
    if (!hasRequiredStaticId(question.source)) {
      addValidationIssue(
        issues,
        file,
        source,
        questionBase,
        `${tag} questions[${questionIndex}].id is required by the Plan renderer schema; add a stable string id.`,
      );
    }
    if (!hasRequiredStaticString(question.source, "title")) {
      addValidationIssue(
        issues,
        file,
        source,
        questionBase,
        `${tag} questions[${questionIndex}].title is required by the Plan renderer schema; add a non-empty string title.`,
      );
    }
    if (
      !hasRequiredEnumLiteral(question.source, "mode", [
        "single",
        "multi",
        "freeform",
      ])
    ) {
      addValidationIssue(
        issues,
        file,
        source,
        questionBase,
        `${tag} questions[${questionIndex}].mode is required by the Plan renderer schema; use "single", "multi", or "freeform".`,
      );
    }
    const options = readTopLevelObjectProperty(question.source, "options");
    if (!options) return;
    const optionObjects = extractTopLevelObjectLiterals(options.value);
    if (!optionObjects) {
      addValidationIssue(
        issues,
        file,
        source,
        questionBase + options.valueStart,
        `${tag} questions[${questionIndex}].options must be an inline array of object literals.`,
      );
      return;
    }
    optionObjects.forEach((option, optionIndex) => {
      const optionBase = questionBase + options.valueStart + option.start;
      if (!hasRequiredStaticId(option.source)) {
        addValidationIssue(
          issues,
          file,
          source,
          optionBase,
          `${tag} questions[${questionIndex}].options[${optionIndex}].id is required by the Plan renderer schema; add a stable string id.`,
        );
      }
      if (!hasRequiredStaticString(option.source, "label")) {
        addValidationIssue(
          issues,
          file,
          source,
          optionBase,
          `${tag} questions[${questionIndex}].options[${optionIndex}].label is required by the Plan renderer schema; add a non-empty string label.`,
        );
      }
    });
  });
}

function lintChecklistShape(
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const scanSource = maskCodeRegions(source);
  const re = /<Checklist\b/g;
  let match: RegExpExecArray | null;
  while ((match = re.exec(scanSource))) {
    const start = match.index;
    const openingEnd = findJsxOpeningTagEnd(scanSource, start);
    if (openingEnd < 0) continue;
    const opening = source.slice(start, openingEnd + 1);
    const items = readJsxAttribute(opening, "items");
    if (!items) continue;
    if (items.kind !== "expression") {
      addValidationIssue(
        issues,
        file,
        source,
        start + items.start,
        "Checklist items must be an inline array expression with stable item ids.",
      );
      continue;
    }
    const objects = extractTopLevelObjectLiterals(items.value);
    if (!objects) {
      addValidationIssue(
        issues,
        file,
        source,
        start + items.start,
        "Checklist items must be an inline array of object literals so local check can validate the renderer schema.",
      );
      continue;
    }
    checkChecklistItemList(objects, start + items.start, file, source, issues);
  }
}

function lintQuestionFormShape(
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const scanSource = maskCodeRegions(source);
  const re = /<(QuestionForm|VisualQuestions)\b/g;
  let match: RegExpExecArray | null;
  while ((match = re.exec(scanSource))) {
    const start = match.index;
    const tag = match[1] ?? "QuestionForm";
    const openingEnd = findJsxOpeningTagEnd(scanSource, start);
    if (openingEnd < 0) continue;
    const opening = source.slice(start, openingEnd + 1);
    const questions = readJsxAttribute(opening, "questions");
    if (!questions) {
      addValidationIssue(
        issues,
        file,
        source,
        start,
        `${tag} requires a questions array with at least one question object.`,
      );
      continue;
    }
    if (questions.kind !== "expression") {
      addValidationIssue(
        issues,
        file,
        source,
        start + questions.start,
        `${tag} questions must be an inline array expression with stable question ids.`,
      );
      continue;
    }
    const questionObjects = extractTopLevelObjectLiterals(questions.value);
    if (!questionObjects || questionObjects.length === 0) {
      addValidationIssue(
        issues,
        file,
        source,
        start + questions.start,
        `${tag} questions must be a non-empty inline array of object literals.`,
      );
      continue;
    }
    checkQuestionObjectList(
      questionObjects,
      start + questions.start,
      tag,
      file,
      source,
      issues,
    );
  }
}

function staticStringLiteralValue(
  value: string | undefined,
): string | undefined {
  if (value === undefined) return undefined;
  const trimmed = value.trim();
  const quote = trimmed[0];
  if (quote !== '"' && quote !== "'" && quote !== "`") return undefined;
  if (!trimmed.endsWith(quote) || trimmed.length < 2) return undefined;
  if (quote === "`" && /\$\{/.test(trimmed)) return undefined;
  return trimmed.slice(1, -1);
}

// Container blocks authored with a JSON attribute array (`<TabsBlock tabs={[…]}
// />`) carry their children as nested block objects, not top-level JSX tags, so
// the tag-based linters above never inspect them — the exact "false green" the
// renderer catches because it validates the whole parsed block tree. Walk those
// nested `blocks: [...]` arrays and enforce the same per-block required fields,
// recursing through nested containers. This is still a subset of the renderer
// schema (which is why `verify` is the authority), but it closes the common
// nested checklist / question-form / missing-id case offline.
const NESTED_CONTAINER_TAGS: ReadonlyArray<{ tag: string; attr: string }> = [
  { tag: "TabsBlock", attr: "tabs" },
  { tag: "Tabs", attr: "tabs" },
  { tag: "Columns", attr: "columns" },
];

function lintNestedContainerEntry(
  entrySource: string,
  entryBase: number,
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const blocksProp = readTopLevelObjectProperty(entrySource, "blocks");
  if (!blocksProp) return;
  const blockObjects = extractTopLevelObjectLiterals(blocksProp.value);
  if (!blockObjects) return;
  const blocksBase = entryBase + blocksProp.valueStart;
  for (const block of blockObjects) {
    lintNestedBlock(
      block.source,
      blocksBase + block.start,
      file,
      source,
      issues,
    );
  }
}

function lintNestedBlock(
  blockSource: string,
  blockBase: number,
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const typeProp = readTopLevelObjectProperty(blockSource, "type");
  const type = staticStringLiteralValue(typeProp?.value);
  if (!hasRequiredStaticId(blockSource)) {
    addValidationIssue(
      issues,
      file,
      source,
      blockBase,
      `Nested ${type ?? "block"} is missing a required string \`id\`; the Plan renderer schema validates every nested block.`,
    );
  }
  const dataProp = readTopLevelObjectProperty(blockSource, "data");
  if (!dataProp) return;
  const dataBase = blockBase + dataProp.valueStart;

  if (type === "checklist") {
    const itemsProp = readTopLevelObjectProperty(dataProp.value, "items");
    if (!itemsProp) return;
    const items = extractTopLevelObjectLiterals(itemsProp.value);
    if (items) {
      checkChecklistItemList(
        items,
        dataBase + itemsProp.valueStart,
        file,
        source,
        issues,
      );
    }
    return;
  }
  // visual-questions shares question-form's schema; lint both.
  if (type === "question-form" || type === "visual-questions") {
    const questionsProp = readTopLevelObjectProperty(
      dataProp.value,
      "questions",
    );
    if (!questionsProp) return;
    const questionObjects = extractTopLevelObjectLiterals(questionsProp.value);
    if (questionObjects) {
      checkQuestionObjectList(
        questionObjects,
        dataBase + questionsProp.valueStart,
        type,
        file,
        source,
        issues,
      );
    }
    return;
  }
  if (type === "tabs" || type === "columns") {
    const innerAttr = type === "tabs" ? "tabs" : "columns";
    const innerProp = readTopLevelObjectProperty(dataProp.value, innerAttr);
    if (!innerProp) return;
    const innerEntries = extractTopLevelObjectLiterals(innerProp.value);
    if (!innerEntries) return;
    const innerBase = dataBase + innerProp.valueStart;
    for (const entry of innerEntries) {
      lintNestedContainerEntry(
        entry.source,
        innerBase + entry.start,
        file,
        source,
        issues,
      );
    }
  }
}

function lintNestedContainerBlocks(
  file: string,
  source: string,
  issues: LocalPlanValidationIssue[],
) {
  const scanSource = maskCodeRegions(source);
  for (const { tag, attr } of NESTED_CONTAINER_TAGS) {
    const re = new RegExp(`<${tag}\\b`, "g");
    let match: RegExpExecArray | null;
    while ((match = re.exec(scanSource))) {
      const start = match.index;
      const openingEnd = findJsxOpeningTagEnd(scanSource, start);
      if (openingEnd < 0) continue;
      const opening = source.slice(start, openingEnd + 1);
      const attrValue = readJsxAttribute(opening, attr);
      if (!attrValue || attrValue.kind !== "expression") continue;
      const entries = extractTopLevelObjectLiterals(attrValue.value);
      if (!entries) continue;
      const entriesBase = start + attrValue.start;
      for (const entry of entries) {
        lintNestedContainerEntry(
          entry.source,
          entriesBase + entry.start,
          file,
          source,
          issues,
        );
      }
    }
  }
}

// Blank out fenced code blocks and inline code spans (preserving newlines and
// length) so block-tag linters don't trip on documentation examples written in
// prose — e.g. an inline `<WireframeBlock><Screen>...</Screen></WireframeBlock>`
// example is not a real block to validate. Real blocks (outside code) are left
// intact, so their offsets/line numbers stay correct. Without this the default
// `plan local init` scaffold fails its own `plan local check`/`serve` lint.
function maskCodeRegions(source: string): string {
  const blank = (s: string) => s.replace(/[^\n]/g, " ");
  return source.replace(/```[\s\S]*?```/g, blank).replace(/`[^`\n]*`/g, blank);
}

export function validateLocalPlanFiles(
  files: LocalPlanFiles,
): LocalPlanValidationIssue[] {
  const issues: LocalPlanValidationIssue[] = [];
  for (const entry of localPlanSourceEntries(files)) {
    const source = maskCodeRegions(entry.source);
    lintWireframeBlocks(entry.file, source, issues);
    lintColumnsBlocks(entry.file, source, issues);
    lintChecklistShape(entry.file, entry.source, issues);
    lintQuestionFormShape(entry.file, entry.source, issues);
    lintNestedContainerBlocks(entry.file, entry.source, issues);
  }
  return issues;
}

export function assertLocalPlanFilesValid(files: LocalPlanFiles): void {
  const issues = validateLocalPlanFiles(files);
  if (issues.length === 0) return;
  const details = issues
    .slice(0, 8)
    .map((issue) => `${issue.file}:${issue.line} ${issue.message}`)
    .join("\n");
  const overflow =
    issues.length > 8 ? `\n...plus ${issues.length - 8} more issues` : "";
  throw new Error(
    `Local plan source validation failed:\n${details}${overflow}\nRun \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and update the MDX to the documented block shapes.`,
  );
}

export function buildLocalPlanPreviewHtml(
  input: LocalPlanPreviewInput,
): string {
  const files = readLocalPlanFiles(input.dir);
  assertLocalPlanFilesValid(files);
  const parsed = stripFrontmatter(files.planMdx);
  const title =
    input.title ||
    parsed.frontmatter.title ||
    firstHeading(parsed.body) ||
    path.basename(files.dir);
  const brief = input.brief || parsed.frontmatter.brief || "";
  const kind = input.kind || normalizeKind(parsed.frontmatter.kind);
  const blocks = splitMdxBlocks(parsed.body);
  const sourceFiles = [
    ["plan.mdx", files.planMdx],
    ["canvas.mdx", files.canvasMdx],
    ["prototype.mdx", files.prototypeMdx],
    [".plan-state.json", files.stateJson],
  ].filter((entry): entry is [string, string] => Boolean(entry[1]));

  return `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>${escapeHtml(title)}</title>
  <style>
    :root {
      color-scheme: light dark;
      --bg: #f8fafc;
      --paper: #ffffff;
      --ink: #0f172a;
      --muted: #64748b;
      --line: #cbd5e1;
      --accent: #2563eb;
      --soft: #eff6ff;
      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
    }
    @media (prefers-color-scheme: dark) {
      :root {
        --bg: #020617;
        --paper: #0f172a;
        --ink: #e2e8f0;
        --muted: #94a3b8;
        --line: #334155;
        --soft: #172554;
      }
    }
    body { margin: 0; background: var(--bg); color: var(--ink); }
    main { max-width: 1040px; margin: 0 auto; padding: 40px 20px 56px; }
    header { margin-bottom: 28px; }
    h1 { font-size: clamp(2rem, 5vw, 3.5rem); line-height: 1; margin: 0 0 12px; }
    h2 { font-size: 1.35rem; margin: 28px 0 10px; }
    h3 { font-size: 1.05rem; margin: 0 0 8px; }
    p, li { line-height: 1.65; }
    .meta { display: flex; flex-wrap: wrap; gap: 8px; color: var(--muted); font-size: 0.9rem; }
    .pill { border: 1px solid var(--line); border-radius: 999px; padding: 4px 10px; background: var(--paper); }
    .notice { background: var(--soft); border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; margin: 18px 0; }
    .block, details { background: var(--paper); border: 1px solid var(--line); border-radius: 8px; padding: 18px; margin: 14px 0; }
    .component summary { cursor: pointer; color: var(--accent); font-weight: 650; }
    pre { overflow: auto; border-radius: 8px; border: 1px solid var(--line); padding: 14px; background: rgba(148, 163, 184, 0.12); }
    code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 0.9rem; }
    .source-tabs { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 14px; }
  </style>
</head>
<body>
  <main>
    <header>
      <div class="meta">
        <span class="pill">${kind === "recap" ? "Visual recap" : "Visual plan"}</span>
        <span class="pill">Local-files mode</span>
        <span class="pill">No DB writes</span>
      </div>
      <h1>${escapeHtml(title)}</h1>
      ${brief ? `<p>${escapeHtml(brief)}</p>` : ""}
      <div class="notice">
        This preview was generated entirely from local files. It does not call
        the Plan MCP server, the Plan app action surface, a hosted service, or a
        database. Edit the MDX files and regenerate this preview to update it.
      </div>
    </header>
    <section>
      ${blocks
        .map((block) =>
          block.type === "component"
            ? `<details class="component block" open><summary>${escapeHtml(
                block.name || "MDX component",
              )}</summary><pre><code>${escapeHtml(block.value)}</code></pre></details>`
            : `<article class="block">${renderMarkdownish(block.value)}</article>`,
        )
        .join("\n")}
    </section>
    <section>
      <h2>Local Source Files</h2>
      <div class="source-tabs">
        ${sourceFiles
          .map(
            ([name, source]) =>
              `<details><summary>${escapeHtml(name)}</summary><pre><code>${escapeHtml(
                source,
              )}</code></pre></details>`,
          )
          .join("\n")}
      </div>
    </section>
  </main>
</body>
</html>
`;
}

export function writeLocalPlanPreview(input: {
  dir: string;
  out?: string;
  kind?: LocalPlanKind;
  title?: string;
  brief?: string;
  appUrl?: string;
  open?: boolean;
  openUrl?: (url: string) => OpenLocalUrlResult;
}): LocalPlanPreviewResult {
  const dir = path.resolve(input.dir);
  const files = readLocalPlanFiles(dir);
  assertLocalPlanFilesValid(files);
  const parsed = stripFrontmatter(files.planMdx);
  const kind = input.kind || normalizeKind(parsed.frontmatter.kind);
  const title =
    input.title ||
    parsed.frontmatter.title ||
    firstHeading(parsed.body) ||
    path.basename(dir);
  const out = input.out ? path.resolve(input.out) : undefined;
  if (out) {
    fs.mkdirSync(path.dirname(out), { recursive: true });
    fs.writeFileSync(out, buildLocalPlanPreviewHtml({ ...input, dir, kind }));
  }
  const result: LocalPlanPreviewResult = {
    ok: true,
    dir,
    ...(out ? { out } : {}),
    url: out ? pathToFileURL(out).href : localPlanPreviewUrl(dir, input.appUrl),
    title,
    kind,
    files: localPlanFileList(files),
  };
  if (!input.open) return result;

  const openResult = (input.openUrl || openLocalUrl)(result.url);
  return {
    ...result,
    opened: openResult.ok,
    openCommand: openResult.command,
    ...(openResult.error ? { openError: openResult.error } : {}),
  };
}

function readLocalPlanBridgeComments(dir: string): LocalPlanBridgeComment[] {
  try {
    const raw = fs.readFileSync(
      path.join(dir, LOCAL_PLAN_COMMENTS_FILE),
      "utf-8",
    );
    const parsed = JSON.parse(raw);
    return Array.isArray(parsed)
      ? (parsed as LocalPlanBridgeComment[]).filter(
          (comment) => comment && typeof comment.id === "string",
        )
      : [];
  } catch {
    return [];
  }
}

function writeLocalPlanBridgeComments(
  dir: string,
  comments: LocalPlanBridgeComment[],
): void {
  const target = path.join(dir, LOCAL_PLAN_COMMENTS_FILE);
  if (comments.length === 0) {
    fs.rmSync(target, { force: true });
    return;
  }
  fs.writeFileSync(target, `${JSON.stringify(comments, null, 2)}\n`, "utf-8");
}

function normalizeBridgeCommentString(value: unknown, fallback = ""): string {
  return typeof value === "string" ? value : fallback;
}

function normalizeBridgeCommentNullableString(value: unknown): string | null {
  const text = typeof value === "string" ? value.trim() : "";
  return text || null;
}

function normalizeBridgeCommentStatus(value: unknown): string {
  return value === "resolved" ? "resolved" : "open";
}

function newLocalBridgeCommentId(): string {
  return `cmt_${crypto.randomBytes(8).toString("hex")}`;
}

function applyLocalPlanBridgeCommentUpdate(
  dir: string,
  update: LocalPlanBridgeCommentUpdate,
): LocalPlanBridgeComment[] {
  const existing = readLocalPlanBridgeComments(dir);
  const byId = new Map(existing.map((comment) => [comment.id, comment]));
  const now = new Date().toISOString();
  const planId = `local-${path.basename(dir)}`;

  for (const input of update.comments ?? []) {
    const id =
      normalizeBridgeCommentNullableString(input.id) ??
      newLocalBridgeCommentId();
    const prev = byId.get(id);
    const status = normalizeBridgeCommentStatus(input.status ?? prev?.status);
    const message =
      typeof input.message === "string" ? input.message : prev?.message;
    if (!message?.trim()) continue;

    if (prev) {
      byId.set(id, {
        ...prev,
        parentCommentId:
          normalizeBridgeCommentNullableString(input.parentCommentId) ??
          prev.parentCommentId,
        sectionId:
          normalizeBridgeCommentNullableString(input.sectionId) ??
          prev.sectionId,
        kind: normalizeBridgeCommentString(input.kind, prev.kind),
        status,
        anchor:
          typeof input.anchor === "string" || input.anchor === null
            ? input.anchor
            : prev.anchor,
        message,
        authorEmail:
          normalizeBridgeCommentNullableString(input.authorEmail) ??
          prev.authorEmail,
        authorName:
          normalizeBridgeCommentNullableString(input.authorName) ??
          prev.authorName,
        resolutionTarget: "agent",
        mentions: [],
        mentionsJson: null,
        resolvedAt:
          status === "resolved"
            ? (input.resolvedAt ?? prev.resolvedAt ?? now)
            : null,
        resolvedBy:
          status === "resolved"
            ? (input.resolvedBy ?? prev.resolvedBy ?? LOCAL_PLAN_OWNER_EMAIL)
            : null,
        updatedAt: now,
      });
      continue;
    }

    byId.set(id, {
      id,
      planId,
      parentCommentId: normalizeBridgeCommentNullableString(
        input.parentCommentId,
      ),
      sectionId: normalizeBridgeCommentNullableString(input.sectionId),
      kind: normalizeBridgeCommentString(input.kind, "annotation"),
      status,
      anchor: normalizeBridgeCommentNullableString(input.anchor),
      message,
      createdBy: "human",
      authorEmail:
        normalizeBridgeCommentNullableString(input.authorEmail) ??
        LOCAL_PLAN_OWNER_EMAIL,
      authorName: normalizeBridgeCommentNullableString(input.authorName),
      resolutionTarget: "agent",
      mentions: [],
      mentionsJson: null,
      resolvedBy: status === "resolved" ? LOCAL_PLAN_OWNER_EMAIL : null,
      resolvedAt: status === "resolved" ? now : null,
      consumedAt: null,
      deletedAt: null,
      deletedBy: null,
      createdAt: now,
      updatedAt: now,
    });
  }

  for (const id of update.deletedCommentIds ?? []) {
    byId.delete(id);
    for (const comment of byId.values()) {
      if (comment.parentCommentId === id) byId.delete(comment.id);
    }
  }

  const comments = [...byId.values()].sort((a, b) =>
    a.createdAt === b.createdAt
      ? a.id.localeCompare(b.id)
      : a.createdAt.localeCompare(b.createdAt),
  );
  writeLocalPlanBridgeComments(dir, comments);
  return comments;
}

function buildLocalPlanBridgePayload(input: {
  dir: string;
  kind?: LocalPlanKind;
  title?: string;
  brief?: string;
  // `verify` brings the bridge up only to exercise transport + the authoritative
  // renderer check, so it must not be short-circuited by the weaker offline lint.
  skipSourceValidation?: boolean;
}): LocalPlanBridgePayload {
  const dir = path.resolve(input.dir);
  const files = readLocalPlanFiles(dir);
  if (!input.skipSourceValidation) assertLocalPlanFilesValid(files);
  const parsed = stripFrontmatter(files.planMdx);
  const kind = input.kind || normalizeKind(parsed.frontmatter.kind);
  const title =
    input.title ||
    parsed.frontmatter.title ||
    firstHeading(parsed.body) ||
    path.basename(dir);
  const brief = input.brief || parsed.frontmatter.brief || "";
  const comments = readLocalPlanBridgeComments(dir);

  return {
    ok: true,
    version: 1,
    source: "agent-native-local-bridge",
    localOnly: true,
    slug: path.basename(dir),
    dir,
    title,
    brief,
    kind,
    updatedAt: latestLocalPlanMtime(dir, files),
    files: localPlanFileList(files),
    mdx: localPlanMdxFolder(files),
    comments,
  };
}

function latestLocalPlanMtime(dir: string, files: LocalPlanFiles): string {
  const candidates = [
    path.join(dir, "plan.mdx"),
    ...(files.canvasMdx ? [path.join(dir, "canvas.mdx")] : []),
    ...(files.prototypeMdx ? [path.join(dir, "prototype.mdx")] : []),
    ...(files.stateJson ? [path.join(dir, ".plan-state.json")] : []),
    path.join(dir, LOCAL_PLAN_COMMENTS_FILE),
    ...Object.keys(files.assets ?? {}).map((filename) =>
      path.join(dir, "assets", filename),
    ),
  ];
  let latest = 0;
  for (const file of candidates) {
    try {
      latest = Math.max(latest, fs.statSync(file).mtimeMs);
    } catch {
      // Ignore files deleted between the read and stat passes.
    }
  }
  return new Date(latest || Date.now()).toISOString();
}

function sendBridgeJson(
  res: ServerResponse,
  status: number,
  payload: unknown,
): void {
  res.writeHead(status, {
    "access-control-allow-origin": "*",
    "access-control-allow-methods": "GET, POST, OPTIONS",
    "access-control-allow-headers": "content-type",
    // Required when the hosted HTTPS Plan UI fetches this localhost bridge.
    "access-control-allow-private-network": "true",
    "cache-control": "no-store",
    "content-type": "application/json; charset=utf-8",
    "x-agent-native-local-bridge": "1",
  });
  res.end(`${JSON.stringify(payload)}\n`);
}

function readBridgeJsonBody(req: IncomingMessage): Promise<unknown> {
  return new Promise((resolve, reject) => {
    let raw = "";
    req.setEncoding("utf-8");
    req.on("data", (chunk) => {
      raw += chunk;
      if (raw.length > LOCAL_PLAN_BRIDGE_COMMENT_BODY_LIMIT) {
        reject(new Error("Local plan comment update is too large."));
        req.destroy();
      }
    });
    req.on("end", () => {
      if (!raw.trim()) {
        resolve({});
        return;
      }
      try {
        resolve(JSON.parse(raw));
      } catch {
        reject(new Error("Local plan comment update must be JSON."));
      }
    });
    req.on("error", reject);
  });
}

function normalizeBridgeCommentUpdatePayload(
  payload: unknown,
): LocalPlanBridgeCommentUpdate {
  if (!payload || typeof payload !== "object") return {};
  const input = payload as LocalPlanBridgeCommentUpdate;
  return {
    comments: Array.isArray(input.comments) ? input.comments : [],
    deletedCommentIds: Array.isArray(input.deletedCommentIds)
      ? input.deletedCommentIds.filter((id) => typeof id === "string")
      : [],
  };
}

function bridgeRequestUrl(req: IncomingMessage): URL {
  return new URL(req.url || "/", "http://127.0.0.1");
}

function bridgeHostForUrl(host: string): string {
  if (host === "0.0.0.0" || host === "::") return "127.0.0.1";
  return host;
}

export async function startLocalPlanBridge(input: {
  dir: string;
  kind?: LocalPlanKind;
  title?: string;
  brief?: string;
  appUrl?: string;
  host?: string;
  port?: number;
  token?: string;
  open?: boolean;
  urlFile?: string | false;
  openUrl?: (url: string) => OpenLocalUrlResult;
  skipSourceValidation?: boolean;
}): Promise<LocalPlanBridgeServer> {
  const dir = path.resolve(input.dir);
  const initialPayload = buildLocalPlanBridgePayload({
    dir,
    kind: input.kind,
    title: input.title,
    brief: input.brief,
    skipSourceValidation: input.skipSourceValidation,
  });
  const token = input.token || crypto.randomBytes(24).toString("base64url");
  const host = input.host || "127.0.0.1";
  const appUrl = normalizeBridgeAppUrl(input.appUrl);
  const server = http.createServer((req, res) => {
    if (req.method === "OPTIONS") {
      sendBridgeJson(res, 204, "");
      return;
    }

    const url = bridgeRequestUrl(req);
    if (
      url.pathname !== "/local-plan.json" &&
      url.pathname !== "/local-plan-comments.json"
    ) {
      sendBridgeJson(res, 404, { ok: false, error: "Not found." });
      return;
    }
    if (url.searchParams.get("token") !== token) {
      sendBridgeJson(res, 403, { ok: false, error: "Invalid bridge token." });
      return;
    }
    if (url.pathname === "/local-plan.json" && req.method !== "GET") {
      sendBridgeJson(res, 405, { ok: false, error: "Method not allowed." });
      return;
    }
    if (url.pathname === "/local-plan-comments.json" && req.method !== "POST") {
      sendBridgeJson(res, 405, { ok: false, error: "Method not allowed." });
      return;
    }

    void (async () => {
      try {
        if (url.pathname === "/local-plan-comments.json") {
          const body = await readBridgeJsonBody(req);
          applyLocalPlanBridgeCommentUpdate(
            dir,
            normalizeBridgeCommentUpdatePayload(body),
          );
        }
        sendBridgeJson(
          res,
          200,
          buildLocalPlanBridgePayload({
            dir,
            kind: input.kind,
            title: input.title,
            brief: input.brief,
            skipSourceValidation: input.skipSourceValidation,
          }),
        );
      } catch (error) {
        sendBridgeJson(res, 500, {
          ok: false,
          error: error instanceof Error ? error.message : String(error),
        });
      }
    })();
  });

  await new Promise<void>((resolve, reject) => {
    const onError = (error: Error) => {
      server.off("listening", onListening);
      reject(error);
    };
    const onListening = () => {
      server.off("error", onError);
      resolve();
    };
    server.once("error", onError);
    server.once("listening", onListening);
    server.listen(input.port ?? 0, host);
  });

  const address = server.address();
  if (!address || typeof address === "string") {
    server.close();
    throw new Error("Local plan bridge did not bind to a TCP port.");
  }

  const bridgeUrl = `http://${bridgeHostForUrl(host)}:${address.port}/local-plan.json?token=${encodeURIComponent(
    token,
  )}`;
  const url = localPlanBridgePageUrl({ dir, bridgeUrl, appUrl });
  const urlFile =
    input.urlFile === false
      ? undefined
      : writeLocalPlanUrlFile(dir, url, input.urlFile);
  const openResult = input.open
    ? (input.openUrl || openLocalUrl)(url)
    : undefined;

  return {
    server,
    result: {
      ok: true,
      dir,
      url,
      ...(urlFile ? { urlFile } : {}),
      bridgeUrl,
      appUrl,
      title: initialPayload.title,
      kind: initialPayload.kind,
      files: initialPayload.files,
      host,
      port: address.port,
      ...(openResult
        ? {
            opened: openResult.ok,
            openCommand: openResult.command,
            ...(openResult.error ? { openError: openResult.error } : {}),
          }
        : {}),
    },
  };
}

function localPlanBridgeWarnings(input: {
  appUrl: string;
  bridgeUrl: string;
}): string[] {
  const warnings: string[] = [];
  try {
    const appUrl = new URL(input.appUrl);
    const bridgeUrl = new URL(input.bridgeUrl);
    if (appUrl.protocol === "https:" && bridgeUrl.protocol === "http:") {
      warnings.push(
        `Chrome/Edge will ask for Local Network access so ${appUrl.hostname} can read this loopback bridge. Allow it; if you denied it, re-enable Local Network access in the ${appUrl.hostname} site settings, then retry.`,
      );
      warnings.push(
        "Safari may block the hosted HTTPS Plan UI from reading the HTTP localhost bridge. Use Chrome/Chromium/Edge, or pass --app-url http://localhost:8096 when running a local Plan app.",
      );
    }
  } catch {
    // The URLs were normalized earlier; ignore defensive parse failures.
  }
  return warnings;
}

const VALIDATE_LOCAL_PLAN_ACTION = "validate-local-plan-source";

function isLoopbackAppUrl(value: string): boolean {
  try {
    const hostname = new URL(value).hostname.toLowerCase();
    return (
      hostname === "localhost" ||
      hostname === "[::1]" ||
      hostname === "::1" ||
      hostname === "0.0.0.0" ||
      hostname.startsWith("127.")
    );
  } catch {
    return false;
  }
}

/**
 * Ask a loopback Plan app to validate the folder against its real renderer schema
 * (`parsePlanMdxFolder` + `planContentSchema`) via the public, no-DB
 * `validate-local-plan-source` action. This is what makes `verify`
 * authoritative without transmitting local plan source off-device. Remote app
 * URLs are intentionally skipped: local-files privacy mode must never POST MDX
 * or assets to a hosted validation action. Degrades gracefully (`ran: false`)
 * when no local Plan app is running or it predates the action.
 */
export async function fetchRendererValidation(input: {
  appUrl: string;
  files: LocalPlanFiles;
  fetchFn?: typeof fetch;
}): Promise<RendererValidation> {
  const fetchFn = input.fetchFn ?? fetch;
  const endpoint = planActionEndpoint(input.appUrl, VALIDATE_LOCAL_PLAN_ACTION);
  if (!isLoopbackAppUrl(input.appUrl)) {
    return {
      ran: false,
      endpoint,
      error:
        "Skipped remote renderer validation to keep local plan source on this device.",
    };
  }
  try {
    const response = await fetchActionWithTimeout(
      endpoint,
      {
        method: "POST",
        headers: {
          accept: "application/json",
          "content-type": "application/json",
        },
        body: JSON.stringify({ mdx: localPlanMdxFolder(input.files) }),
      },
      fetchFn,
    );
    if (!response.ok) {
      const detail = await response.text().catch(() => "");
      return {
        ran: false,
        endpoint,
        error: `${VALIDATE_LOCAL_PLAN_ACTION} failed ${response.status} ${
          response.statusText
        }: ${sanitizeHttpDetail(detail, 300)}`,
      };
    }
    const json = (await response.json().catch(() => null)) as
      | (Record<string, unknown> & { result?: Record<string, unknown> })
      | null;
    const body =
      json && isRecord(json.result) ? json.result : (json ?? undefined);
    if (!body || typeof body.valid !== "boolean") {
      return {
        ran: false,
        endpoint,
        error: `${VALIDATE_LOCAL_PLAN_ACTION} returned an unexpected payload.`,
      };
    }
    const issues = Array.isArray(body.issues)
      ? body.issues.filter(isRecord).map((issue) => ({
          path: typeof issue.path === "string" ? issue.path : "",
          message:
            typeof issue.message === "string" ? issue.message : "Invalid value",
        }))
      : [];
    return { ran: true, endpoint, valid: body.valid, issues };
  } catch (err) {
    return {
      ran: false,
      endpoint,
      error: err instanceof Error ? err.message : String(err),
    };
  }
}

function rendererValidationWarnings(
  validation: RendererValidation,
  offlineIssues: LocalPlanValidationIssue[],
): string[] {
  if (!validation.ran) {
    const base = `Plan content was NOT validated against a local renderer schema (${
      validation.error ?? "validate endpoint unavailable"
    }). Fell back to the offline lint. For authoritative validation without data egress, run a local Plan app that exposes ${VALIDATE_LOCAL_PLAN_ACTION} and pass --app-url http://localhost:8096.`;
    if (offlineIssues.length === 0) return [base];
    const preview = offlineIssues
      .slice(0, 8)
      .map((issue) => `${issue.file}:${issue.line} ${issue.message}`)
      .join("; ");
    const overflow =
      offlineIssues.length > 8 ? ` (+${offlineIssues.length - 8} more)` : "";
    return [base, `Offline lint rejected this plan: ${preview}${overflow}`];
  }
  if (validation.valid) return [];
  const issues = validation.issues ?? [];
  const preview = issues
    .slice(0, 8)
    .map((issue) =>
      issue.path ? `${issue.path}: ${issue.message}` : issue.message,
    )
    .join("; ");
  const overflow = issues.length > 8 ? ` (+${issues.length - 8} more)` : "";
  return [
    `Renderer schema rejected this plan — it will not render. ${preview}${overflow}`,
  ];
}

export async function verifyLocalPlanBridge(input: {
  dir: string;
  kind?: LocalPlanKind;
  title?: string;
  brief?: string;
  appUrl?: string;
  host?: string;
  port?: number;
  token?: string;
  urlFile?: string | false;
  fetchFn?: typeof fetch;
}): Promise<LocalPlanVerifyResult> {
  const fetchFn = input.fetchFn ?? fetch;
  const files = readLocalPlanFiles(input.dir);
  const bridge = await startLocalPlanBridge({
    dir: input.dir,
    kind: input.kind,
    title: input.title,
    brief: input.brief,
    appUrl: input.appUrl,
    host: input.host,
    port: input.port,
    token: input.token,
    urlFile: input.urlFile,
    // Don't let the weaker offline lint abort the bridge before the authoritative
    // renderer check runs — verify reports the renderer's verdict, not the lint's.
    skipSourceValidation: true,
  });

  try {
    const preflight = await fetchFn(bridge.result.bridgeUrl, {
      method: "OPTIONS",
      headers: {
        origin: bridge.result.appUrl,
        "access-control-request-method": "GET",
        "access-control-request-private-network": "true",
      },
    });
    const response = await fetchFn(bridge.result.bridgeUrl, {
      method: "GET",
      headers: { accept: "application/json" },
    });
    const payload = (await response.json().catch(() => null)) as
      | (LocalPlanBridgePayload & { mdx?: LocalPlanBridgeMdxFolder })
      | null;
    const mdxFiles = payload?.mdx
      ? Object.keys(payload.mdx).filter((file) => file !== "assets/")
      : undefined;
    const bridgeOk =
      response.ok &&
      payload?.ok === true &&
      payload.source === "agent-native-local-bridge" &&
      payload.localOnly === true &&
      Boolean(payload.mdx?.["plan.mdx"]);
    const preflightOk =
      preflight.status === 204 &&
      preflight.headers.get("access-control-allow-origin") === "*" &&
      preflight.headers.get("access-control-allow-private-network") === "true";
    const validation = await fetchRendererValidation({
      appUrl: bridge.result.appUrl,
      files,
      fetchFn,
    });
    // The renderer's verdict is authoritative and gates `ok`. When it could not
    // run (old/unreachable Plan app), fall back to the offline lint as the
    // content signal so verify still catches the common cases offline instead
    // of silently passing unvalidated content.
    const offlineIssues = validation.ran ? [] : validateLocalPlanFiles(files);
    const contentOk = validation.ran
      ? validation.valid === true
      : offlineIssues.length === 0;
    return {
      ok: bridgeOk && preflightOk && contentOk,
      dir: bridge.result.dir,
      url: bridge.result.url,
      ...(bridge.result.urlFile ? { urlFile: bridge.result.urlFile } : {}),
      bridgeUrl: bridge.result.bridgeUrl,
      appUrl: bridge.result.appUrl,
      title: bridge.result.title,
      kind: bridge.result.kind,
      files: bridge.result.files,
      preflight: {
        status: preflight.status,
        allowOrigin: preflight.headers.get("access-control-allow-origin"),
        allowPrivateNetwork: preflight.headers.get(
          "access-control-allow-private-network",
        ),
      },
      bridge: {
        status: response.status,
        ok: bridgeOk,
        ...(payload?.source ? { source: payload.source } : {}),
        ...(typeof payload?.localOnly === "boolean"
          ? { localOnly: payload.localOnly }
          : {}),
        ...(Array.isArray(payload?.files) ? { files: payload.files } : {}),
        ...(mdxFiles ? { mdxFiles } : {}),
        ...(payload?.error ? { error: payload.error } : {}),
      },
      validation,
      warnings: [
        ...localPlanBridgeWarnings({
          appUrl: bridge.result.appUrl,
          bridgeUrl: bridge.result.bridgeUrl,
        }),
        ...rendererValidationWarnings(validation, offlineIssues),
      ],
    };
  } finally {
    await new Promise<void>((resolve) => bridge.server.close(() => resolve()));
  }
}

function writeLocalPlanSkeleton(input: {
  dir?: string;
  title: string;
  brief?: string;
  kind: LocalPlanKind;
  force?: boolean;
}): { ok: true; dir: string; files: string[] } {
  const dir = path.resolve(
    input.dir || path.join(defaultPlansDir(), localPlanFolderName(input.title)),
  );
  const planPath = path.join(dir, "plan.mdx");
  if (fs.existsSync(planPath) && !input.force) {
    throw new Error(
      `${planPath} already exists. Pass --force to replace the skeleton.`,
    );
  }
  fs.mkdirSync(dir, { recursive: true });
  const title = input.title;
  const brief =
    input.brief ||
    (input.kind === "recap"
      ? "Local visual recap generated without Plan app database writes."
      : "Local visual plan generated without Plan app database writes.");
  const mdx = [
    "---",
    `title: "${title.replace(/"/g, '\\"')}"`,
    `brief: "${brief.replace(/"/g, '\\"')}"`,
    `kind: "${input.kind}"`,
    "localOnly: true",
    "---",
    "",
    `# ${title}`,
    "",
    brief,
    "",
    "## Review Surface",
    "",
    "Author the structured plan or recap here. You can add Agent-Native Plan MDX",
    'blocks such as `<WireframeBlock><Screen surface="browser">...</Screen></WireframeBlock>`,',
    "`<Diagram />`, `<TabsBlock />`, `<FileTree />`, or `<Diff />`; the local",
    "preview will show the source without publishing it to the Plan app.",
    "",
  ].join("\n");
  fs.writeFileSync(planPath, mdx, "utf-8");
  fs.writeFileSync(
    path.join(dir, ".plan-state.json"),
    JSON.stringify(
      {
        localOnly: true,
        kind: input.kind,
        createdAt: new Date().toISOString(),
      },
      null,
      2,
    ) + "\n",
    "utf-8",
  );
  return { ok: true, dir, files: ["plan.mdx", ".plan-state.json"] };
}

function runInit(args: Record<string, string | boolean>): void {
  const title = optionalArg(args, "title") || "Untitled local visual plan";
  const result = writeLocalPlanSkeleton({
    dir: optionalArg(args, "dir"),
    title,
    brief: optionalArg(args, "brief"),
    kind: normalizeKind(optionalArg(args, "kind")),
    force: boolArg(args, "force"),
  });
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}

function runCheck(args: Record<string, string | boolean>): void {
  const dir = stringArg(args, "dir");
  const files = readLocalPlanFiles(dir);
  assertLocalPlanFilesValid(files);
  const parsed = stripFrontmatter(files.planMdx);
  const result = {
    ok: true,
    noDb: true,
    validation: "lint-passed",
    validationScope: "offline-lint",
    note: "Quick offline lint only — NOT the full Plan renderer schema. A green here does not guarantee the plan renders. Run `plan local verify` against a Plan app for authoritative validation before handing off.",
    dir: files.dir,
    title: parsed.frontmatter.title || firstHeading(parsed.body),
    kind: normalizeKind(parsed.frontmatter.kind),
    files: {
      "plan.mdx": Buffer.byteLength(files.planMdx),
      ...(files.canvasMdx
        ? { "canvas.mdx": Buffer.byteLength(files.canvasMdx) }
        : {}),
      ...(files.prototypeMdx
        ? { "prototype.mdx": Buffer.byteLength(files.prototypeMdx) }
        : {}),
      ...(files.stateJson
        ? { ".plan-state.json": Buffer.byteLength(files.stateJson) }
        : {}),
      ...(files.assets
        ? Object.fromEntries(
            Object.entries(files.assets).map(([filename, base64]) => [
              `assets/${filename}`,
              Buffer.byteLength(base64, "base64"),
            ]),
          )
        : {}),
    },
  };
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}

export function readVisualAnswerSourcePayload(
  sourcePath: string,
): VisualAnswerSourcePayload {
  let parsed: unknown;
  try {
    parsed = JSON.parse(fs.readFileSync(sourcePath, "utf-8"));
  } catch (error) {
    throw new Error(
      `Could not read ${sourcePath}: ${
        error instanceof Error ? error.message : String(error)
      }`,
    );
  }
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new Error(`${sourcePath} must contain a JSON object.`);
  }
  const source = parsed as Record<string, unknown>;
  const mdx = source.mdx;
  if (!mdx || typeof mdx !== "object" || Array.isArray(mdx)) {
    throw new Error(`${sourcePath} must contain an mdx object.`);
  }
  const planMdx = (mdx as Record<string, unknown>)["plan.mdx"];
  if (typeof planMdx !== "string" || planMdx.trim().length === 0) {
    throw new Error(
      `${sourcePath} mdx["plan.mdx"] must be a non-empty string.`,
    );
  }
  return source as VisualAnswerSourcePayload;
}

export async function publishVisualAnswerSource(
  input: PublishVisualAnswerInput,
): Promise<{ ok: true; url: string; out: string }> {
  const cwd = input.cwd ?? process.cwd();
  const sourcePath =
    input.sourcePath ?? path.join(cwd, VISUAL_ANSWER_SOURCE_FILENAME);
  const out = input.out ?? path.join(cwd, VISUAL_ANSWER_URL_FILENAME);
  const token = input.token.trim();
  if (!token) throw new Error("Plan publish token is empty.");

  const source = readVisualAnswerSourcePayload(sourcePath);
  const question = input.question ?? source.question;
  if (!question?.trim()) {
    throw new Error(
      `Missing visual answer question. Pass --question or set question in ${sourcePath}.`,
    );
  }
  const body = {
    question,
    ...(input.prevPlanId ? { planId: input.prevPlanId } : {}),
    ...(source.title ? { title: source.title } : {}),
    ...(source.brief ? { brief: source.brief } : {}),
    visibility: input.visibility ?? "org",
    source: "imported",
    ...((input.repo ?? source.repoPath)
      ? { repoPath: input.repo ?? source.repoPath }
      : {}),
    ...((input.sourceUrl ?? source.sourceUrl)
      ? { sourceUrl: input.sourceUrl ?? source.sourceUrl }
      : {}),
    sourceType: normalizeVisualAnswerSourceType(
      input.sourceType ?? source.sourceType,
    ),
    currentFocus: `visual answer: ${question.trim().slice(0, 120)}`,
    status: "review",
    mdx: source.mdx,
  };

  const endpoint = planActionEndpoint(input.appUrl, "visual-answer");
  const fetchFn = input.fetchFn ?? fetch;
  const response = await fetchActionWithTimeout(
    endpoint,
    {
      method: "POST",
      headers: {
        accept: "application/json",
        "content-type": "application/json",
        authorization: `Bearer ${token}`,
      },
      body: JSON.stringify(body),
    },
    fetchFn,
  );
  const text = await response.text().catch((error) => String(error));
  if (!response.ok) {
    throw new Error(
      `visual-answer failed ${response.status} ${
        response.statusText
      }: ${sanitizeHttpDetail(text, 800)}`,
    );
  }
  let result: unknown = null;
  try {
    result = text ? JSON.parse(text) : null;
  } catch {
    throw new Error("visual-answer returned non-JSON output.");
  }
  const url = visualAnswerUrlFromPublishResult(result, input.appUrl);
  if (!url) {
    throw new Error(
      "visual-answer succeeded but did not return a usable /plans/<id> URL or plan id.",
    );
  }
  fs.writeFileSync(path.resolve(out), `${url}\n`, "utf-8");
  return { ok: true, url, out };
}

async function runVisualAnswer(
  subcommand: string | undefined,
  args: Record<string, string | boolean>,
): Promise<void> {
  if (
    subcommand === undefined ||
    subcommand === "help" ||
    subcommand === "--help" ||
    subcommand === "-h" ||
    args.help === true ||
    args.h === true
  ) {
    process.stdout.write(HELP);
    return;
  }
  if (subcommand !== "publish") {
    process.stderr.write(
      `Unknown plan visual-answer subcommand: ${subcommand}\n${HELP}`,
    );
    process.exit(1);
  }
  const appUrl =
    optionalArg(args, "app-url") ||
    process.env.PLAN_VISUAL_ANSWER_APP_URL ||
    process.env.PLAN_RECAP_APP_URL ||
    DEFAULT_PLAN_APP_URL;
  const token =
    optionalArg(args, "token") ||
    process.env.PLAN_VISUAL_ANSWER_TOKEN ||
    process.env.PLAN_RECAP_TOKEN ||
    "";
  try {
    const result = await publishVisualAnswerSource({
      appUrl,
      token,
      question: optionalArg(args, "question"),
      sourcePath: optionalArg(args, "source") ?? VISUAL_ANSWER_SOURCE_FILENAME,
      out: optionalArg(args, "out") ?? VISUAL_ANSWER_URL_FILENAME,
      prevPlanId: optionalArg(args, "prev-plan-id"),
      repo: optionalArg(args, "repo"),
      sourceUrl: optionalArg(args, "source-url"),
      sourceType: optionalArg(args, "source-type"),
      visibility: normalizeVisibility(optionalArg(args, "visibility")),
    });
    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
  } catch (error) {
    process.stdout.write(
      `${JSON.stringify(
        {
          ok: false,
          reason: error instanceof Error ? error.message : String(error),
        },
        null,
        2,
      )}\n`,
    );
    process.exit(1);
  }
}

function runPreview(args: Record<string, string | boolean>): void {
  const result = writeLocalPlanPreview({
    dir: stringArg(args, "dir"),
    out: optionalArg(args, "out"),
    appUrl: optionalArg(args, "app-url"),
    title: optionalArg(args, "title"),
    brief: optionalArg(args, "brief"),
    open: boolArg(args, "open"),
    kind: optionalArg(args, "kind")
      ? normalizeKind(optionalArg(args, "kind"))
      : undefined,
  });
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}

async function runServe(args: Record<string, string | boolean>): Promise<void> {
  const portValue = optionalArg(args, "port");
  const port = portValue ? Number(portValue) : undefined;
  if (portValue && (!Number.isInteger(port) || port! < 0 || port! > 65535)) {
    throw new Error("--port must be an integer between 0 and 65535.");
  }

  const bridge = await startLocalPlanBridge({
    dir: stringArg(args, "dir"),
    appUrl: optionalArg(args, "app-url"),
    title: optionalArg(args, "title"),
    brief: optionalArg(args, "brief"),
    host: optionalArg(args, "host"),
    port,
    open: boolArg(args, "open"),
    urlFile: optionalArg(args, "url-file") || optionalArg(args, "out"),
    kind: optionalArg(args, "kind")
      ? normalizeKind(optionalArg(args, "kind"))
      : undefined,
  });

  process.stdout.write(`${JSON.stringify(bridge.result, null, 2)}\n`);
  process.stderr.write(
    [
      `Local Plan bridge running at ${bridge.result.bridgeUrl}`,
      bridge.result.urlFile
        ? `Open URL written to ${bridge.result.urlFile}`
        : "",
      ...localPlanBridgeWarnings({
        appUrl: bridge.result.appUrl,
        bridgeUrl: bridge.result.bridgeUrl,
      }),
      "Keep this bridge command running while the Plan page is open; stopping it makes this URL unreachable.",
      "Press Ctrl+C to stop.",
    ]
      .filter(Boolean)
      .join("\n") + "\n",
  );

  await new Promise<void>((resolve) => {
    let stopped = false;
    const cleanup = () => {
      process.off("SIGINT", stop);
      process.off("SIGTERM", stop);
    };
    const stop = () => {
      if (stopped) return;
      stopped = true;
      cleanup();
      bridge.server.close(() => resolve());
    };
    process.once("SIGINT", stop);
    process.once("SIGTERM", stop);
  });
}

async function runVerify(
  args: Record<string, string | boolean>,
): Promise<void> {
  const portValue = optionalArg(args, "port");
  const port = portValue ? Number(portValue) : undefined;
  if (portValue && (!Number.isInteger(port) || port! < 0 || port! > 65535)) {
    throw new Error("--port must be an integer between 0 and 65535.");
  }

  const result = await verifyLocalPlanBridge({
    dir: stringArg(args, "dir"),
    appUrl: optionalArg(args, "app-url"),
    title: optionalArg(args, "title"),
    brief: optionalArg(args, "brief"),
    host: optionalArg(args, "host"),
    port,
    urlFile: optionalArg(args, "url-file") || optionalArg(args, "out") || false,
    kind: optionalArg(args, "kind")
      ? normalizeKind(optionalArg(args, "kind"))
      : undefined,
  });
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
  if (!result.ok) process.exit(1);
}

async function runBlocks(
  args: Record<string, string | boolean>,
): Promise<void> {
  const format = normalizePlanBlockFormat(optionalArg(args, "format"));
  const appUrl =
    optionalArg(args, "app-url") ||
    process.env.PLAN_BLOCKS_APP_URL ||
    process.env.PLAN_RECAP_APP_URL ||
    DEFAULT_PLAN_APP_URL;
  const out = optionalArg(args, "out") || defaultPlanBlocksOut(format);
  const useClack = Boolean(process.stdout.isTTY) && !boolArg(args, "json");
  let stopSpinner: ((message?: string) => void) | undefined;
  let clack: typeof import("@clack/prompts") | undefined;

  if (useClack) {
    clack = await import("@clack/prompts");
    const spinner = clack.spinner();
    spinner.start("Fetching Plan block catalog");
    stopSpinner = (message?: string) => spinner.stop(message);
  }

  try {
    const result = await fetchPlanBlockCatalog({
      appUrl,
      format,
      out,
    });
    if (!useClack || !clack) {
      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
      return;
    }
    stopSpinner?.("Fetched Plan block catalog");
    clack.note(
      [
        `Output   ${path.resolve(result.out)}`,
        `Format   ${result.format}`,
        typeof result.count === "number" ? `Blocks   ${result.count}` : "",
        "Privacy  No plan content sent",
      ]
        .filter(Boolean)
        .join("\n"),
      "Plan block catalog",
    );
    clack.outro(`Wrote ${result.out}`);
  } catch (error) {
    if (useClack && clack) {
      stopSpinner?.("Plan block catalog fetch failed");
      clack.cancel(error instanceof Error ? error.message : String(error));
      process.exit(1);
    }
    throw error;
  }
}

const HELP = `agent-native plan — local Agent-Native Plan helpers

Usage:
  agent-native plan blocks [--format reference|schema] [--app-url <url>] [--out <file>] [--json]
  agent-native plan visual-answer publish --question <text> [--source visual-answer-source.json] [--out visual-answer-url.txt] [--repo owner/name] [--source-url <url>] [--app-url <url>] [--token <planToken>]
  agent-native plan serve --dir <folder> [--app-url <url>] [--kind plan|recap] [--open] [--port <port>] [--url-file <file>]
  agent-native plan local init --title <title> [--brief <text>] [--kind plan|recap] [--dir <folder>] [--force]
  agent-native plan local check --dir <folder>
  agent-native plan local serve --dir <folder> [--app-url <url>] [--kind plan|recap] [--open] [--port <port>] [--url-file <file>]
  agent-native plan local verify --dir <folder> [--app-url <url>] [--kind plan|recap] [--port <port>]
  agent-native plan local preview --dir <folder> [--app-url <url>] [--kind plan|recap] [--open] [--out preview.html]

The blocks command fetches the no-auth, read-only get-plan-blocks catalog from
the Plan app and writes plan-blocks.md (or plan-blocks.schema.json). It sends no
plan content and is safe for local-files authoring before writing MDX. It uses a
clack UI in interactive terminals and prints JSON for non-interactive shells or
when --json is passed.

The visual-answer publish command sends a coding-agent-authored
visual-answer-source.json file to the Plan app's visual-answer action and writes
visual-answer-url.txt. The source file should contain a question, optional
title/brief/repoPath/sourceUrl, and MDX files under mdx. It is the terminal
handoff for /visual-answer workflows after a coding agent has inspected code via
the local repo, the Plan bridge, or GitHub and authored structured Plan blocks.

The local subcommands are the privacy-focused no-DB path. They only read and
write local files: plan.mdx, optional canvas.mdx, optional prototype.mdx, and
optional .plan-state.json. They do not call the Plan MCP server, the Plan app
write actions, hosted storage, or SQLite.

Common flow:
  agent-native plan blocks --out plan-blocks.md
  agent-native plan local init --title "Checkout review" --kind plan
  agent-native plan local serve --dir plans/checkout-review --open

\`plan local serve\` starts a tiny localhost bridge and opens the hosted Plan UI
against that local-only source. The hosted app fetches the MDX from localhost in
the browser; it does not write plan content to the hosted database. The served
URL is written to \`.plan-url\` by default; pass \`--url-file\` to choose a
different local-only file. On macOS, \`--open\` prefers Chromium browsers.
Chrome/Edge will ask for Local Network access to read the loopback bridge; if
you deny it, re-enable Local Network access in the plan.agent-native.com site
settings and retry. Keep the bridge command running while the page is open.
Safari may block the hosted HTTPS page from reading the HTTP localhost bridge;
use a Chromium browser or a local Plan app via \`--app-url http://localhost:8096\`.
Use \`plan local verify\` for headless bridge/CORS diagnostics that exit cleanly.
Use \`plan local preview\` for a local Plan dev server route. \`preview --out\` is
a legacy/debug escape hatch that writes a standalone static HTML file.
\`plan serve\` is kept as a compatibility alias for \`plan local serve\`.
`;

export async function runPlan(argv: string[]): Promise<void> {
  const [area, sub, ...rest] = argv;
  if (area === "blocks") {
    await runBlocks(parseArgs(argv.slice(1)));
    return;
  }
  if (area === "serve") {
    const args = parseArgs(argv.slice(1));
    if (args.help === true || args.h === true) {
      process.stdout.write(HELP);
      return;
    }
    await runServe(args);
    return;
  }
  if (area === "visual-answer") {
    await runVisualAnswer(sub, parseArgs(rest));
    return;
  }
  if (area !== "local") {
    // Bare `agent-native plan` / `plan help` / `plan --help` → show help on
    // stdout and exit 0 (informational, not an error).
    if (
      area === undefined ||
      area === "help" ||
      area === "--help" ||
      area === "-h"
    ) {
      process.stdout.write(HELP);
      return;
    }
    // A non-empty, unrecognised area (e.g. `agent-native plan lokal`) is an
    // error: print to stderr so the CI log captures it, and exit 1 so callers
    // can detect the failure. This mirrors the existing behaviour for unknown
    // subcommands inside `plan local`.
    process.stderr.write(`Unknown plan area: ${area}\n${HELP}`);
    process.exit(1);
  }
  const args = parseArgs(rest);
  // `plan local <sub> --help` / `-h` shows help instead of running the
  // subcommand (e.g. `plan local init --help` must not scaffold a folder).
  if (args.help === true || args.h === true) {
    process.stdout.write(HELP);
    return;
  }
  switch (sub) {
    case "init":
      runInit(args);
      return;
    case "check":
      runCheck(args);
      return;
    case "preview":
      runPreview(args);
      return;
    case "serve":
      await runServe(args);
      return;
    case "verify":
      await runVerify(args);
      return;
    case "help":
    case "--help":
    case "-h":
    case undefined:
      process.stdout.write(HELP);
      return;
    default:
      process.stderr.write(`Unknown plan local subcommand: ${sub}\n${HELP}`);
      process.exit(1);
  }
}