Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

27.8 KB
Raw Blame
import { existsSync } from 'node:fs';
import { resolve } from 'node:path';
import {
  AdvisoryWarningSchema,
  BrokenLinkSchema,
  BrokenLinkSuppressionSchema,
  currentCliCommandName,
  getAgentCanonicalDescriptors,
  isAuditEmptyScopeWarning,
  SERVER_TIMEOUT_ERROR_PREFIX,
  SERVER_UNREACHABLE_ERROR_PREFIX,
  UNREADABLE_WARNINGS_TEXT,
  validateDocName,
} from '@inkeep/open-knowledge-core';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import type { Config } from '../../config/schema.ts';
import { SUPPORTED_DOC_EXTENSIONS } from '../../doc-extensions.ts';
import type { LocalApiDispatch } from '../../http/local-api-dispatch.ts';
import type { AgentIdentity } from '../agent-identity.ts';
import { resolveWithinRoot } from './path-safety.ts';

export type ServerInstance = McpServer;
export type ConfigOrResolver = Config | ((cwd?: string) => Promise<Config>);

/** The agent-identity fields every mutating route accepts for attribution (precedent #24/#25). */
export function agentIdentityFields(identity: AgentIdentity | undefined): Record<string, unknown> {
  return identity
    ? {
        agentId: identity.connectionId,
        agentName: identity.displayName,
        clientName: identity.clientInfo?.name,
        colorSeed: identity.colorSeed,
      }
    : {};
}
export const ROUTED_CWD_DESCRIPTION =
  'Absolute OK project/worktree path. Routed stdio: required until set unless one client root exists. Project-bound HTTP: optional, confined to its root.';

export const CANONICAL_COMPONENT_GUIDANCE = `Canonical ids: ${getAgentCanonicalDescriptors()
  .map((descriptor) => descriptor.name)
  .join(
    ', ',
  )}. Call palette({components:[ids]}) before authoring for syntax/props, markdown-native forms, Mermaid and themed html preview for interactive charts/demos. Other JSX stays raw MDX when no canonical fits.`;

const SUMMARY_TRANSPORT_CAP = 200;

export const summaryArgSchema = z
  .string()
  .max(SUMMARY_TRANSPORT_CAP)
  .optional()
  .describe(
    'Optional one-line user-outcome description (≤80 chars). Appears as a bullet in the timeline.',
  );

export const VERSION_FIELD_DESCRIBE =
  'A 40-character commit SHA identifying a saved version. Produced by `checkpoint`, listed by `history` as `entries[].version`, and consumed here — the same `version` field name across all three.';

export const versionInputSchema = z
  .string()
  .length(40)
  .regex(/^[0-9a-f]+$/i)
  .describe(VERSION_FIELD_DESCRIBE);

export const previewUrlOutputField = z
  .string()
  .nullable()
  .describe('Route-only preview URL (`/#/<doc>`, no host:port), or null when no UI is running.');

export const previewUrlSourceField = z
  .string()
  .optional()
  .describe('How the previewUrl was resolved (e.g. the UI lock).');

export const previousPreviewUrlField = z
  .string()
  .optional()
  .describe('Route of the prior/removed path, for closing a stale preview tab.');

export const summaryOutputSchema = z
  .object({
    value: z.string(),
    truncatedFrom: z.number().optional(),
    hint: z.string().optional(),
  })
  .describe('Normalized change-note summary, when one was recorded.');

export const looseObjectArray = z.array(z.record(z.string(), z.unknown()));

export const previewAttachWarningField = z
  .record(z.string(), z.unknown())
  .optional()
  .describe('Preview-attach hint (`{ action, previewUrl?, message? }`) when relevant.');

const brokenLinksOutputField = z
  .array(BrokenLinkSchema)
  .describe(
    'Outbound internal links in the just-written doc that do not resolve. Always present — `[]` means every link resolves UNLESS `brokenLinkSuppression` is also present, in which case a project policy withheld findings, or `warnings` carries `link-check-deferred`, in which case the links were not checked because the server is still starting or busy with other writes. A withholding that arrives in a shape this build cannot validate is dropped rather than relayed, so `brokenLinkSuppression` stays absent even though findings were withheld. The `audit` tool is the surface that discloses that case, through its `warnings`. Each: `{ href (as written), resolvedTo (the docName or content-root file path it pointed at, or null), reason: "no-such-doc" | "no-such-file" | "unresolvable" | "excluded" }`. `excluded` means the file exists on disk but a .gitignore or .okignore rule keeps it out of the project; a `!` rule in .okignore re-includes it or its folder. Report-only — the write landed regardless; fix in a follow-up edit.',
  );

const brokenLinkSuppressionOutputField = BrokenLinkSuppressionSchema.optional().describe(
  'Present ONLY when a project policy omitted detected broken links from `brokenLinks` — so an empty `brokenLinks` beside it does NOT mean every link resolves. `{ reason, count }`; `reason` today is `"reserved-log-policy"` (a reserved `log.md` records history whose links are expected not to resolve) and is an open token, so treat one you do not recognize as a withholding policy all the same. `count` is how many findings were withheld; the hrefs are deliberately not returned, because none of them is yours to repair.',
);

export function docExtensionOnDisk(
  contentDir: string,
  docName: string,
): (typeof SUPPORTED_DOC_EXTENSIONS)[number] | undefined {
  for (const ext of SUPPORTED_DOC_EXTENSIONS) {
    const contained = resolveWithinRoot(contentDir, `${docName}${ext}`);
    if (contained.ok && existsSync(contained.abs)) return ext;
  }
  return undefined;
}

export const documentResultBaseShape = {
  summary: summaryOutputSchema.optional(),
  warnings: z
    .array(AdvisoryWarningSchema)
    .min(1)
    .optional()
    .describe(
      "Advisory entries discriminated by `kind`. Write-integrity kinds — `content-divergence` (converged Y.Text didn't byte-match what you composed) and `disk-edit-reconciled` (an out-of-band disk edit was folded in before your write) — mean re-read the doc. The renderability kind `mermaid-parse-error` means the write landed but that fence will not render — fix it and re-edit. `link-check-deferred` means links were not checked because the server is still starting or busy with other writes — that doc is re-checked only by a later write or edit of it, or an `audit`, which can time out until startup finishes.",
    ),
  brokenLinks: brokenLinksOutputField,
  brokenLinkSuppression: brokenLinkSuppressionOutputField,
  templateHint: z
    .array(z.object({ name: z.string(), description: z.string().optional() }))
    .min(1)
    .optional()
    .describe(
      "Templates the parent folder offers, present only when a create passed no `template`. A nudge — the write already landed; pass `template` next time to match the folder's shape.",
    ),
} as const;

export function nestDocResult(
  preview: { url: string; source: string } | null | undefined,
  warning: Record<string, unknown> | undefined,
  docFields: Record<string, unknown>,
): Record<string, unknown> {
  const structured: Record<string, unknown> = {};
  if (preview) {
    structured.previewUrl = preview.url;
    structured.previewUrlSource = preview.source;
  }
  if (warning) structured.warning = warning;
  if (Object.keys(docFields).length > 0) structured.document = docFields;
  return structured;
}

export function requestFailureText(result: { [key: string]: unknown }): string {
  const title = typeof result.error === 'string' ? result.error : 'request failed';
  const detail =
    typeof result.detail === 'string' && result.detail.length > 0 ? ` (${result.detail})` : '';
  const retryAfter =
    typeof result.retryAfterSeconds === 'number'
      ? ` Retry after ${result.retryAfterSeconds}s.`
      : '';
  return `${title}${detail}${retryAfter}`;
}

export function errorTextWithDetail(
  result: { [key: string]: unknown },
  invalidRequestAdvice?: string,
): string {
  const advice =
    result.type === 'urn:ok:error:invalid-request' &&
    result.contentControlAdmission === true &&
    invalidRequestAdvice
      ? ` ${invalidRequestAdvice}`
      : '';
  return `Error: ${requestFailureText(result)}${advice}`;
}

export function textResult(text: string, isError?: boolean) {
  return {
    content: [{ type: 'text' as const, text }],
    ...(isError ? { isError: true as const } : {}),
  };
}

export const TEXT_CHANNEL_FIELD = z
  .string()
  .optional()
  .describe(
    'Auto-duplicated body text. `textPlusStructured` mirrors the visible body here as a Claude / Claude Desktop client-quirk workaround (those clients hide `content[]` when `structuredContent` is present). Internal — programmatic consumers should prefer the `content[0].text` channel.',
  );

export function outputSchemaWithText<S extends z.ZodRawShape>(
  shape: S,
): Omit<{ text: typeof TEXT_CHANNEL_FIELD }, keyof S> & S {
  return {
    text: TEXT_CHANNEL_FIELD,
    ...shape,
  } as Omit<{ text: typeof TEXT_CHANNEL_FIELD }, keyof S> & S;
}

export function textPlusStructured<T>(text: string, structured: T, isError?: boolean) {
  const structuredContent: { text: string } & Record<string, unknown> = {
    text,
    ...(structured as unknown as Record<string, unknown>),
  };
  return {
    content: [{ type: 'text' as const, text }],
    structuredContent,
    ...(isError ? { isError: true as const } : {}),
  };
}

export function hocuspocusNotRunningError(): string {
  return `Error: Hocuspocus server is not running. Start it with \`${currentCliCommandName()} start\`, then retry.\nDo not fall back to native file edits for in-scope markdown; route writes through OpenKnowledge so attribution and live sync stay intact.`;
}

export type ServerUrlOrResolver =
  | string
  | undefined
  | ((cwd?: string) => Promise<string | undefined>);

export async function resolveServerUrl(
  x: ServerUrlOrResolver,
  cwd?: string,
): Promise<string | undefined> {
  return typeof x === 'function' ? await x(cwd) : x;
}

async function resolveConfig(x: ConfigOrResolver, cwd?: string): Promise<Config> {
  return typeof x === 'function' ? await x(cwd) : x;
}

export async function resolveProjectConfigContext(
  resolveCwd: (explicit?: string) => Promise<string>,
  config: ConfigOrResolver,
  explicitCwd?: string,
): Promise<
  { ok: true; cwd: string; executionCwd: string; config: Config } | { ok: false; error: string }
> {
  let cwd: string;
  try {
    cwd = await resolveCwd(explicitCwd);
  } catch (err) {
    return { ok: false, error: err instanceof Error ? err.message : String(err) };
  }
  const executionCwd = explicitCwd !== undefined ? resolve(explicitCwd) : cwd;
  try {
    const resolvedConfig = await resolveConfig(config, cwd);
    return { ok: true, cwd, executionCwd, config: resolvedConfig };
  } catch (err) {
    return { ok: false, error: err instanceof Error ? err.message : String(err) };
  }
}

export async function requireProjectServer(
  resolveCwd: (explicit?: string) => Promise<string>,
  config: ConfigOrResolver,
  serverUrl: ServerUrlOrResolver,
  explicitCwd?: string,
): Promise<
  | { ok: true; cwd: string; executionCwd: string; config: Config; url: string }
  | { ok: false; result: ReturnType<typeof textResult> }
> {
  const context = await resolveProjectServerContext(resolveCwd, config, serverUrl, explicitCwd);
  if (!context.ok) return { ok: false, result: textResult(`Error: ${context.error}`, true) };
  if (!context.url) return { ok: false, result: textResult(hocuspocusNotRunningError(), true) };
  return {
    ok: true,
    cwd: context.cwd,
    executionCwd: context.executionCwd,
    config: context.config,
    url: context.url,
  };
}

export async function resolveProjectServerContext(
  resolveCwd: (explicit?: string) => Promise<string>,
  config: ConfigOrResolver,
  serverUrl: ServerUrlOrResolver,
  explicitCwd?: string,
): Promise<
  | { ok: true; cwd: string; executionCwd: string; config: Config; url: string | undefined }
  | { ok: false; error: string }
> {
  const configContext = await resolveProjectConfigContext(resolveCwd, config, explicitCwd);
  if (!configContext.ok) {
    return configContext;
  }
  const { cwd, executionCwd, config: resolvedConfig } = configContext;
  try {
    const url = await resolveServerUrl(serverUrl, cwd);
    return { ok: true, cwd, executionCwd, config: resolvedConfig, url };
  } catch (err) {
    return { ok: false, error: err instanceof Error ? err.message : String(err) };
  }
}

export function okReservedPathRedirect(path: string): string | null {
  const p = path.replace(/^\/+/, '');
  if (p !== '.ok' && !p.startsWith('.ok/')) return null;
  if (p.startsWith('.ok/skills/')) {
    return 'Skills are authored with the `skill` target, not a raw document path: `write({ skill: { name, description, body?, scope? } })` writes the SKILL.md wherever the skill lives (a NEW skill lands at the project default skill home, e.g. `.agents/skills/<name>/`). To author or improve a skill, use the `open-knowledge-write-skill` skill.';
  }
  if (p.startsWith('.ok/templates/')) {
    return 'Templates are authored with the `template` target (`write({ template: { … } })`), not a raw document path.';
  }
  return 'Paths under `.ok/` are not addressable as documents. Edit folder config/frontmatter via the `folder` target, skills via the `skill` target, and templates via the `template` target.';
}

export function normalizeDocName(
  raw: string,
): { ok: true; docName: string } | { ok: false; error: string } {
  const lower = raw.toLowerCase();
  if (lower.endsWith('.markdown')) {
    return {
      ok: false,
      error: `Error: "${raw}" ends in ".markdown", which is not a supported extension. Use ".md" or ".mdx", or strip the extension to let the server auto-detect.`,
    };
  }
  let candidate = raw;
  let lowerCandidate = lower;
  while (lowerCandidate.endsWith('.mdx') || lowerCandidate.endsWith('.md')) {
    candidate = candidate.slice(0, lowerCandidate.endsWith('.mdx') ? -4 : -3);
    lowerCandidate = candidate.toLowerCase();
  }
  const validation = validateDocName(candidate);
  if (!validation.ok) {
    return { ok: false, error: `Error: "${raw}" is invalid — ${validation.reason}.` };
  }
  return { ok: true, docName: candidate };
}

/**
 * The boundary canonicalizer pattern lets tool handlers stay unaware of HTTP status semantics or
 * the RFC 9457 wire shape (precedent #38).
 */
function normalizeResponse(
  res: { ok: boolean; status: number },
  body: unknown,
): { ok: boolean; [key: string]: unknown } {
  if (res.ok) {
    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
      return { ok: true, data: body };
    }
    const { ok: _ok, ...rest } = body as Record<string, unknown>;
    return { ok: true, ...rest };
  }
  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
    return {
      ok: false,
      error: `Server returned HTTP ${res.status} with non-object body`,
    };
  }
  const record = body as Record<string, unknown>;
  if (typeof record.type === 'string' && typeof record.title === 'string') {
    const { type, title, status, instance, detail, ...extensions } = record;
    return {
      ...extensions,
      ok: false,
      error: title,
      type,
      ...(typeof status === 'number' ? { status } : {}),
      ...(typeof instance === 'string' ? { instance } : {}),
      ...(typeof detail === 'string' ? { detail } : {}),
    };
  }
  const { ok: _ok, error: bodyError, ...rest } = record;
  const fallbackError =
    typeof bodyError === 'string'
      ? bodyError
      : typeof record.message === 'string'
        ? record.message
        : `Server returned HTTP ${res.status}`;
  return { ...rest, ok: false, error: fallbackError };
}

export type ApiTarget = string | { url: string; local: LocalApiDispatch };

export function apiTarget(url: string, local: LocalApiDispatch | undefined): ApiTarget {
  return local ? { url, local } : url;
}

export function isTimeoutError(err: unknown): boolean {
  return (
    err instanceof Error &&
    (err.name === 'TimeoutError' ||
      [err, err.cause].some(
        (cause) =>
          cause instanceof Error &&
          'code' in cause &&
          (cause.code === 'UND_ERR_HEADERS_TIMEOUT' || cause.code === 'UND_ERR_BODY_TIMEOUT'),
      ))
  );
}

export function serverRequestFailure(err: unknown, opts?: { mutating?: boolean }): string {
  const detail = err instanceof Error ? err.message : String(err);
  if (!isTimeoutError(err)) return `${SERVER_UNREACHABLE_ERROR_PREFIX} ${detail}`;
  const caution =
    opts?.mutating === false
      ? ''
      : ' The server may still have applied the request, so check before retrying.';
  return `${SERVER_TIMEOUT_ERROR_PREFIX} ${detail}.${caution}`;
}

async function localApiCall(
  local: LocalApiDispatch,
  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
  path: string,
  serializedBody: string | undefined,
  includeHttpStatus: boolean,
): Promise<{ ok: boolean; [key: string]: unknown } | null> {
  let raw: { status: number; bodyText: string } | null;
  try {
    raw = await local(
      method,
      path,
      serializedBody !== undefined
        ? { body: serializedBody, contentType: 'application/json' }
        : undefined,
    );
  } catch (err) {
    return { ok: false, error: serverRequestFailure(err) };
  }
  if (raw === null) return null;
  const ok = raw.status >= 200 && raw.status <= 299;
  let body: unknown;
  try {
    body = JSON.parse(raw.bodyText);
  } catch (parseErr) {
    const detail = parseErr instanceof Error ? parseErr.message : String(parseErr);
    const statusFields = includeHttpStatus ? { httpStatus: raw.status } : {};
    if (ok) {
      return {
        ok: false,
        ...statusFields,
        error: `Server returned 2xx response with non-JSON body: ${detail}`,
      };
    }
    return {
      ok: false,
      ...statusFields,
      error: `Server returned HTTP ${raw.status} with non-JSON body: ${detail}`,
    };
  }
  const normalized = normalizeResponse({ ok, status: raw.status }, body);
  return includeHttpStatus ? { ...normalized, httpStatus: raw.status } : normalized;
}

export function httpGet(
  base: string,
  path: string,
  signal: AbortSignal,
): Promise<{ ok: boolean; [key: string]: unknown }>;
export function httpGet(
  base: ApiTarget,
  path: string,
): Promise<{ ok: boolean; [key: string]: unknown }>;
export async function httpGet(
  base: ApiTarget,
  path: string,
  signal?: AbortSignal,
): Promise<{ ok: boolean; [key: string]: unknown }> {
  if (typeof base !== 'string') {
    const local = await localApiCall(base.local, 'GET', path, undefined, true);
    if (local !== null) return local;
    base = base.url;
  }
  let res: Response;
  try {
    res = await fetch(`${base}${path}`, { signal: signal ?? AbortSignal.timeout(30_000) });
  } catch (err) {
    return { ok: false, error: serverRequestFailure(err, { mutating: false }) };
  }
  let body: unknown;
  try {
    body = await res.json();
  } catch (parseErr) {
    if (isTimeoutError(parseErr)) {
      return {
        ok: false,
        httpStatus: res.status,
        error: serverRequestFailure(parseErr, { mutating: false }),
      };
    }
    const detail = parseErr instanceof Error ? parseErr.message : String(parseErr);
    if (res.ok) {
      return {
        ok: false,
        httpStatus: res.status,
        error: `Server returned 2xx response with non-JSON body: ${detail}`,
      };
    }
    return {
      ok: false,
      httpStatus: res.status,
      error: `Server returned HTTP ${res.status} with non-JSON body: ${detail}`,
    };
  }
  return { ...normalizeResponse(res, body), httpStatus: res.status };
}

export async function httpGetRows(
  base: ApiTarget,
  path: string,
  field: string,
): Promise<
  { error: string } | { rows: Array<Record<string, unknown>>; data: Record<string, unknown> }
> {
  const result = await httpGet(base, path);
  if (!result.ok) {
    return { error: typeof result.error === 'string' ? result.error : 'request failed' };
  }
  const { ok: _ok, ...data } = result;
  const raw = (data as Record<string, unknown>)[field];
  const rows = Array.isArray(raw) ? (raw as Array<Record<string, unknown>>) : [];
  return { rows, data };
}

async function httpSend(
  method: 'POST' | 'PUT' | 'DELETE',
  base: ApiTarget,
  path: string,
  body?: Record<string, unknown>,
): Promise<{ ok: boolean; [key: string]: unknown }> {
  let serializedBody: string | undefined;
  if (body !== undefined) {
    try {
      serializedBody = JSON.stringify(body);
    } catch (stringifyErr) {
      return {
        ok: false,
        error: `Request body is not JSON-serializable: ${stringifyErr instanceof Error ? stringifyErr.message : String(stringifyErr)}`,
      };
    }
  }
  if (typeof base !== 'string') {
    const local = await localApiCall(base.local, method, path, serializedBody, false);
    if (local !== null) return local;
    base = base.url;
  }
  let res: Response;
  try {
    res = await fetch(`${base}${path}`, {
      method,
      headers: serializedBody !== undefined ? { 'Content-Type': 'application/json' } : undefined,
      body: serializedBody,
      signal: AbortSignal.timeout(30_000),
    });
  } catch (err) {
    return { ok: false, error: serverRequestFailure(err) };
  }
  let parsed: unknown;
  try {
    parsed = await res.json();
  } catch (parseErr) {
    if (isTimeoutError(parseErr)) return { ok: false, error: serverRequestFailure(parseErr) };
    const detail = parseErr instanceof Error ? parseErr.message : String(parseErr);
    if (res.ok) {
      return {
        ok: false,
        error: `Server returned 2xx response with non-JSON body: ${detail}`,
      };
    }
    return {
      ok: false,
      error: `Server returned HTTP ${res.status} with non-JSON body: ${detail}`,
    };
  }
  return normalizeResponse(res, parsed);
}

export function httpPost(
  base: ApiTarget,
  path: string,
  body?: Record<string, unknown>,
): Promise<{ ok: boolean; [key: string]: unknown }> {
  return httpSend('POST', base, path, body);
}

export function httpPut(
  base: ApiTarget,
  path: string,
  body?: Record<string, unknown>,
): Promise<{ ok: boolean; [key: string]: unknown }> {
  return httpSend('PUT', base, path, body);
}

export function httpDelete(
  base: ApiTarget,
  path: string,
): Promise<{ ok: boolean; [key: string]: unknown }> {
  return httpSend('DELETE', base, path);
}

export interface RenameCollisionPair {
  existing: string;
  incoming: string;
  to: string;
}

export function parseRenameCollidingPairs(value: unknown): RenameCollisionPair[] {
  if (!Array.isArray(value)) return [];
  return value.flatMap((entry) => {
    if (!entry || typeof entry !== 'object') return [];
    const { existing, incoming, to } = entry as Record<string, unknown>;
    return typeof existing === 'string' && typeof incoming === 'string' && typeof to === 'string'
      ? [{ existing, incoming, to }]
      : [];
  });
}

export { UNREADABLE_WARNINGS_TEXT };

export function alignWarningCodes(
  warnings: unknown,
  codes: unknown,
  known: ReadonlySet<string>,
): { warnings: string[]; warningCodes?: string[] } {
  if (warnings !== undefined && !Array.isArray(warnings)) {
    return { warnings: [UNREADABLE_WARNINGS_TEXT] };
  }
  const text = (Array.isArray(warnings) ? warnings : []).map((entry) =>
    typeof entry === 'string' ? entry : String(entry),
  );
  const rawCodes = Array.isArray(codes) ? (codes as string[]) : [];
  if (text.length !== rawCodes.length) return { warnings: text };
  return rawCodes.every((code) => known.has(code))
    ? { warnings: text, warningCodes: rawCodes }
    : { warnings: text };
}

export function warningCodesContract(reporter: string): string {
  return `Machine-readable codes aligned 1:1 with \`warnings\` (\`warnings[i]\` is the display text for \`warningCodes[i]\`) — switch on these, never on the English. Absent when ${reporter} sent warning text it did not pair with codes, or paired one with a code this build does not recognise; \`warnings\` still carries the full text either way, so treat a missing field as unknown rather than as an all-clear.`;
}

export const WARNING_CODES_CONTRACT = warningCodesContract('the server');

export function warningsFieldContract(reporter: string): string {
  return `Always emitted, \`[]\` when there were none. \`warningCodes\` accompanies this list 1:1 whenever ${reporter} paired every warning it sent with a code this build recognises; otherwise \`warningCodes\` is absent and this list still carries the full text. \`content[0].text\` lists every warning either way. A \`warnings\` payload in a shape this build cannot read at all becomes one entry saying so, with \`warningCodes\` absent — \`[]\` never means "unreadable".`;
}

export const WARNINGS_FIELD_CONTRACT = warningsFieldContract('the server');

export const AUTHORING_WARNING_CODE_GLOSS =
  '`skill-name-vendor-word`: the name contains a vendor word. `skill-body-too-long`: the body exceeds the 500-line soft cap.';

export const INSTALL_WARNING_CODE_GLOSS =
  '`no-targets`: nothing was projected, no editor is configured for this project. `scripts-present`: the skill ships executable `scripts/` (projected, never auto-run). `no-description`: installed, but its `description` is empty, so agents cannot route to it. `name-conflict`: a DIFFERENT skill already holds that name at a location. `place-path-invalid`: a named location is not a placeable root. `place-fork-refused`: a copy differing from the current source was left alone rather than deleted. `skill-fork-name-unpatched`: a fork rename moved the folder but could not rewrite `name` in its SKILL.md. `links-not-permitted`: the OS refused symlinks, so the named locations are copies that refresh while unedited and fork when edited.';

export const AUDIT_FILE_CAP = 10;
export const AUDIT_FILE_DIAGNOSTIC_CAP = 10;

export const AUDIT_WARNING_CAP = 10;

const ATTRIBUTED_VALIDATION_FAILURE = /^(?:source(?: family)?|validator) "/;

export function capAuditWarnings(warnings: readonly string[]): {
  shownWarnings: string[];
  omittedWarningCount: number;
} {
  const attributed: string[] = [];
  const generic: string[] = [];
  for (const warning of warnings) {
    (ATTRIBUTED_VALIDATION_FAILURE.test(warning) ? attributed : generic).push(warning);
  }
  const shownWarnings = [...attributed, ...generic].slice(0, AUDIT_WARNING_CAP);
  return {
    shownWarnings,
    omittedWarningCount: warnings.length - shownWarnings.length,
  };
}

export function degradationBlock(
  kind: 'Lint' | 'Audit',
  shown: readonly string[],
  omitted = 0,
): string[] {
  const degraded = shown.filter((warning) => !isAuditEmptyScopeWarning(warning));
  const total = degraded.length + omitted;
  if (total === 0) return [];
  return [
    `${kind} incomplete — ${total} warning${total === 1 ? '' : 's'} (findings may be partial):`,
    ...degraded.map((warning) => `  ⚠ ${warning}`),
    ...(omitted > 0 ? [`  … and ${omitted} more warning${omitted === 1 ? '' : 's'}`] : []),
  ];
}

export function zeroFindingsSummary(
  kind: 'Lint' | 'Audit',
  fileCount: number,
  warnings: readonly string[],
  scope: string,
): string {
  if (fileCount === 0 && warnings.some(isAuditEmptyScopeWarning))
    return `No documents were checked${scope}; this scope contains no admitted documents.`;
  const documents = `${fileCount} document${fileCount === 1 ? '' : 's'}${scope}`;
  return warnings.length > 0
    ? `No problems found across ${documents}, but the ${kind.toLowerCase()} could not fully complete.`
    : `No problems across ${documents}.`;
}

export interface FormattableDiagnostic {
  severity?: string;
  range?: { start?: { line?: number } };
  source?: string;
  code?: string;
  message?: string;
}

export function formatDiagnosticLine(d: FormattableDiagnostic): string {
  const marker = d.severity === 'error' ? '✘' : '⚠';
  const startLine = d.range?.start?.line;
  const where = startLine !== undefined ? `line ${startLine + 1}` : 'line ?';
  const flatId = d.source !== undefined && d.code !== undefined ? `${d.source}/${d.code}` : '?';
  return `  ${marker} ${where} ${flatId}: ${d.message ?? ''}`.trimEnd();
}

export function countSummary(errorCount: number, warningCount: number): string {
  const parts: string[] = [];
  if (errorCount > 0) parts.push(`${errorCount} error${errorCount === 1 ? '' : 's'}`);
  if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? '' : 's'}`);
  return parts.length > 0 ? parts.join(', ') : 'no problems';
}