/**
 * T-172…T-175 (A-010) — AI Knowledge Assistant: the five new tools.
 *
 * Each capability gets: a `*_SYSTEM_PROMPT`, a `ToolSpec` (the strict
 * JSON-Schema subset the gateway validates), a `validate*` zod helper for the
 * UNTRUSTED model output, and a prompt renderer. The renderers are also the
 * MockProvider's parse contract (mode "assistant", action per tool) — the
 * unit/integration path exercises the REAL prompt → provider →
 * server-validation loop, exactly like the writing/database/rag/generate
 * capabilities.
 *
 * Security (spec §15, SECURITY_REVIEW §4.8): context is rendered ONLY from
 * the permission-filtered candidate set (the service re-checks VIEW per page
 * via `actorLevel` before it reaches here); every model-emitted page id is
 * filtered against that set before any use or write (no fabricated refs).
 */
import { z } from "zod";

// ---------------------------------------------------------------------------
// Shared render helpers
// ---------------------------------------------------------------------------

/** `[n] <label>\n<text>` — the numbered-source context (RAG contract). */
export function renderNumberedSource(n: number, label: string, text: string, cap = 1200): string {
  return `[${n}] ${label}\n${text.slice(0, cap)}`;
}

/** `<text>` under a plain section header (meeting notes). */
export function renderSection(header: string, text: string, cap = 12000): string {
  return `${header}\n${text.slice(0, cap)}`;
}

/** `[<id>] <title>\n<text>` — the candidate-page context for find-* tools. */
export function renderCandidate(id: string, title: string, text: string, cap = 1200): string {
  return `[${id}] ${title}\n${text.slice(0, cap)}`;
}

interface ToolResult<T> {
  ok: true;
  value: T;
  /** Candidate ids the model emitted that were NOT in the retrieved set. */
  dropped: string[];
}
interface ToolError {
  ok: false;
  feedback: string;
}

// ---------------------------------------------------------------------------
// 1. extract-actions — meeting notes → tasks (written via TasksService)
// ---------------------------------------------------------------------------

export const EXTRACT_ACTIONS_SYSTEM_PROMPT = `You extract action items from meeting notes.
Rules:
- An action item is a concrete task someone should do (an owner mention is optional context).
- "title" is a short imperative summary, max 200 characters, no leading bullet or "action" word.
- "dueDate" is "YYYY-MM-DD" and ONLY when the note states an explicit date; never invent a date.
- Extract at most 10 items, in note order.
- Use ONLY the provided notes. If there are no action items, return an empty list.
Answer by calling the extractActionItems tool.`;

export const EXTRACT_ACTION_ITEMS_TOOL = {
  name: "extractActionItems",
  description: "Return the action items found in the meeting notes.",
  parameters: {
    type: "object",
    properties: {
      actions: {
        type: "array",
        description: "The extracted action items, in note order (max 10).",
        items: {
          type: "object",
          properties: {
            title: { type: "string", description: "Short imperative task summary (max 200 chars)." },
            dueDate: { type: "string", description: "Due date YYYY-MM-DD, only if stated in the notes." },
          },
          required: ["title"],
        },
      },
    },
    required: ["actions"],
  },
} as const;

export interface ExtractedAction {
  title: string;
  dueDate?: string;
}

const actionItemSchema = z.object({
  title: z.string().trim().min(1).max(200),
  dueDate: z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, "dueDate must be YYYY-MM-DD")
    .optional(),
});

export function validateExtractActions(raw: unknown): (ToolResult<ExtractedAction[]> & { value: ExtractedAction[] }) | ToolError {
  const parsed = z
    .object({ actions: z.array(actionItemSchema).max(10) })
    .safeParse(raw);
  if (!parsed.success) {
    return { ok: false, feedback: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") };
  }
  return { ok: true, value: parsed.data.actions, dropped: [] };
}

export function renderExtractPrompt(text: string): string {
  return renderSection("Source (meeting notes):", text);
}

// ---------------------------------------------------------------------------
// 2. generate-faqs — documentation → FAQ draft page
// ---------------------------------------------------------------------------

export const GENERATE_FAQS_SYSTEM_PROMPT = `You generate FAQs from the numbered workspace sources.
Rules:
- Every answer must be grounded in the sources. End each answer with the source marker, e.g. "(per [1])".
- Do NOT invent facts, references, or source numbers that are not in the list.
- At most 15 FAQs. Questions are short; answers are 1-3 sentences.
- If the sources contain nothing FAQ-worthy, return an empty list.
Answer by calling the generateFaqs tool.`;

export const GENERATE_FAQS_TOOL = {
  name: "generateFaqs",
  description: "Return the FAQ draft generated from the sources.",
  parameters: {
    type: "object",
    properties: {
      title: { type: "string", description: "Title of the FAQ page (max 200 chars)." },
      faqs: {
        type: "array",
        description: "The FAQ entries, max 15.",
        items: {
          type: "object",
          properties: {
            question: { type: "string", description: "The question (max 300 chars)." },
            answer: { type: "string", description: "The answer, ending with the source marker like (per [1])." },
          },
          required: ["question", "answer"],
        },
      },
    },
    required: ["title", "faqs"],
  },
} as const;

export interface FaqEntry {
  question: string;
  answer: string;
}

export function validateGenerateFaqs(raw: unknown): (ToolResult<{ title: string; faqs: FaqEntry[] }>) | ToolError {
  const parsed = z
    .object({
      title: z.string().trim().min(1).max(200),
      faqs: z
        .array(
          z.object({
            question: z.string().trim().min(1).max(300),
            answer: z.string().trim().min(1).max(2000),
          })
        )
        .max(15),
    })
    .safeParse(raw);
  if (!parsed.success) {
    return { ok: false, feedback: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") };
  }
  return { ok: true, value: { title: parsed.data.title, faqs: parsed.data.faqs }, dropped: [] };
}

export function renderFaqsPrompt(sources: Array<{ label: string; text: string }>, n: number): string {
  return sources.map((s, i) => renderNumberedSource(i + 1, s.label, s.text)).join("\n\n");
}

// ---------------------------------------------------------------------------
// 3. find-duplicates — near-duplicate documentation (model over candidates)
// ---------------------------------------------------------------------------

export const FIND_DUPLICATES_SYSTEM_PROMPT = `You identify duplicate or near-duplicate documentation pages.
You are given candidate pages, each as "[<id>] <title>" followed by a text excerpt.
Rules:
- A group is 2-6 candidate pages that cover the same topic with substantially overlapping content.
- Cite ONLY page ids from the provided list. Never invent an id.
- "similarity" is 0-1 (your confidence). "reason" is one sentence.
- At most 20 groups. If there are no duplicates, return an empty list.
Answer by calling the findDuplicateGroups tool.`;

export const FIND_DUPLICATE_GROUPS_TOOL = {
  name: "findDuplicateGroups",
  description: "Return groups of candidate pages that are likely duplicates.",
  parameters: {
    type: "object",
    properties: {
      groups: {
        type: "array",
        description: "Duplicate groups (max 20).",
        items: {
          type: "object",
          properties: {
            pageIds: {
              type: "array",
              description: "Candidate page ids in the group (2-6), from the provided list only.",
              items: { type: "string" },
            },
            similarity: { type: "number", description: "Confidence 0-1." },
            reason: { type: "string", description: "One-sentence reason." },
          },
          required: ["pageIds", "similarity", "reason"],
        },
      },
    },
    required: ["groups"],
  },
} as const;

export interface DuplicateGroup {
  pageIds: string[];
  similarity: number;
  reason: string;
}

export function validateDuplicateGroups(
  raw: unknown,
  knownPageIds: Set<string>,
): (ToolResult<DuplicateGroup[]>) | ToolError {
  const parsed = z
    .object({
      groups: z
        .array(
          z.object({
            pageIds: z.array(z.string().min(1)).min(2).max(6),
            similarity: z.number().min(0).max(1),
            reason: z.string().trim().min(1).max(300),
          })
        )
        .max(20),
    })
    .safeParse(raw);
  if (!parsed.success) {
    return { ok: false, feedback: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") };
  }
  // No fabricated refs: drop any id the caller can see is not in the
  // permission-filtered candidate set; discard groups left with <2 known ids.
  const dropped = new Set<string>();
  const groups: DuplicateGroup[] = [];
  for (const g of parsed.data.groups) {
    const kept = g.pageIds.filter((id) => {
      if (knownPageIds.has(id)) return true;
      dropped.add(id);
      return false;
    });
    if (kept.length >= 2) groups.push({ pageIds: kept, similarity: g.similarity, reason: g.reason });
  }
  return { ok: true, value: groups, dropped: [...dropped] };
}

export function renderDuplicatesPrompt(candidates: Array<{ id: string; title: string; text: string }>): string {
  return "Candidate pages:\n" + candidates.map((c) => renderCandidate(c.id, c.title, c.text)).join("\n\n");
}

// ---------------------------------------------------------------------------
// 4. find-stale — outdated pages (server pre-filters by updatedAt, model judges)
// ---------------------------------------------------------------------------

export const FIND_STALE_SYSTEM_PROMPT = `You identify stale or outdated documentation pages.
You are given candidate pages, each as "[<id>] <title> (last updated <date>)" followed by a text excerpt.
Rules:
- Flag a page when its content shows signs of being outdated (old dates, superseded info, obsolete steps).
- Cite ONLY page ids from the provided list. Never invent an id.
- "reason" is one sentence citing what looks stale.
- At most 100 pages. If none look stale, return an empty list.
Answer by calling the findStalePages tool.`;

export const FIND_STALE_PAGES_TOOL = {
  name: "findStalePages",
  description: "Return the candidate pages that appear stale.",
  parameters: {
    type: "object",
    properties: {
      pages: {
        type: "array",
        description: "Stale pages (max 100).",
        items: {
          type: "object",
          properties: {
            pageId: { type: "string", description: "Candidate page id, from the provided list only." },
            reason: { type: "string", description: "One sentence citing what looks stale." },
          },
          required: ["pageId", "reason"],
        },
      },
    },
    required: ["pages"],
  },
} as const;

export interface StalePage {
  pageId: string;
  reason: string;
}

export function validateStalePages(raw: unknown, knownPageIds: Set<string>): (ToolResult<StalePage[]>) | ToolError {
  const parsed = z
    .object({
      pages: z
        .array(
          z.object({
            pageId: z.string().min(1),
            reason: z.string().trim().min(1).max(300),
          })
        )
        .max(100),
    })
    .safeParse(raw);
  if (!parsed.success) {
    return { ok: false, feedback: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") };
  }
  const dropped = new Set<string>();
  const pages: StalePage[] = [];
  for (const p of parsed.data.pages) {
    if (!knownPageIds.has(p.pageId)) {
      dropped.add(p.pageId);
      continue;
    }
    pages.push({ pageId: p.pageId, reason: p.reason });
  }
  return { ok: true, value: pages, dropped: [...dropped] };
}

export function renderStalePrompt(candidates: Array<{ id: string; title: string; text: string; updatedAt: string }>): string {
  return (
    "Candidate pages (not updated in the last days threshold):\n" +
    candidates
      .map((c) => renderCandidate(c.id, `${c.title} (last updated ${c.updatedAt.slice(0, 10)})`, c.text))
      .join("\n\n")
  );
}

// ---------------------------------------------------------------------------
// 5. suggest-metadata — title/description suggestions (apply = normal page PATCH)
//
// CONFLICT (recorded per rule 29 / AGENTS.md): spec §15 says "Suggest owners,
// tags, and review dates", but the data model has NO tag/label or review-date
// column (Page has title, description, reviewState as a workflow enum, no
// owner field beyond createdBy/updatedBy). The capability therefore suggests
// the updatable metadata that EXISTS: title + description. Owners/tags/
// review-dates are recorded as a deferred extension in FEATURE_TRACKER.
// ---------------------------------------------------------------------------

export const SUGGEST_METADATA_SYSTEM_PROMPT = `You suggest improved metadata for a single page.
Rules:
- "title" (max 200 chars) and "description" (1-2 sentences, max 2000 chars).
- Ground both in the page content; do not invent facts.
- Omit a field when the current value is already fine. Provide at least one.
- The suggestion is a PROPOSAL — nothing is written until the user applies it.
Answer by calling the suggestPageMetadata tool.`;

export const SUGGEST_PAGE_METADATA_TOOL = {
  name: "suggestPageMetadata",
  description: "Return the suggested title and/or description for the page.",
  parameters: {
    type: "object",
    properties: {
      title: { type: "string", description: "Suggested title (max 200 chars), if improved." },
      description: { type: "string", description: "Suggested 1-2 sentence description (max 2000 chars), if improved." },
    },
  },
} as const;

export interface PageMetadataSuggestion {
  title?: string;
  description?: string;
}

export function validateMetadataSuggestion(raw: unknown): ToolResult<PageMetadataSuggestion> | ToolError {
  const parsed = z
    .object({
      title: z.string().trim().min(1).max(200).optional(),
      description: z.string().trim().min(1).max(2000).optional(),
    })
    .safeParse(raw);
  if (!parsed.success) {
    return { ok: false, feedback: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") };
  }
  const { title, description } = parsed.data;
  if (!title && !description) {
    return { ok: false, feedback: "Provide at least one of title or description." };
  }
  return { ok: true, value: { title, description }, dropped: [] };
}

export function renderMetadataPrompt(page: { title: string; text: string }): string {
  return renderSection("Page title:", page.title) + "\n\n" + renderSection("Page content:", page.text, 8000);
}

/** The hidden-conversation title prefix for all five capabilities. */
export const ASSISTANT_CONV_PREFIX = "assistant:";