katman-mcp 0.1.0

package/dist/tools/method/lib/routes.js

@@ -0,0 +1,118 @@
+import { normPath } from "./text.js";
+const DYNAMIC_SEG = /^(\[.*\]|:.+|\$.*|\*.*|\(.*\))$/;
+function segments(p) {
+    return p
+        .split(/[?#]/)[0]
+        .split("/")
+        .filter(Boolean)
+        .filter((s) => !/^\(.*\)$/.test(s)); // Next.js route groups aren't URL segments
+}
+/** Default app paths from book appendix A, used only when there is no scan. */
+export const DEFAULT_APP_PREFIXES = ["/app", "/admin", "/api", "/dashboard"];
+/** App/API prefixes to Disallow (never bare prefixes: callers always add a trailing slash). */
+export function appPrefixes(scan, extra = []) {
+    const set = new Set();
+    const conflicts = [];
+    for (const r of scan?.routes ?? []) {
+        if (r.kind !== "app" && r.kind !== "api")
+            continue;
+        const segs = segments(r.path);
+        if (!segs.length)
+            continue;
+        let prefix;
+        if (DYNAMIC_SEG.test(segs[0])) {
+            if (segs.length < 2 || DYNAMIC_SEG.test(segs[1]))
+                continue;
+            prefix = `/*/${segs[1]}`;
+        }
+        else
+            prefix = `/${segs[0]}`;
+        set.add(prefix.toLowerCase());
+    }
+    for (const p of extra) {
+        const s = p.trim();
+        if (!s || s === "/")
+            continue;
+        set.add(("/" + s.replace(/^\/+/, "").replace(/\/+$/, "")).toLowerCase());
+    }
+    const defaulted = !scan && set.size === 0;
+    if (defaulted)
+        DEFAULT_APP_PREFIXES.forEach((p) => set.add(p));
+    // never close a prefix that public pages live under
+    const publicPaths = (scan?.routes ?? []).filter((r) => r.kind === "public" || r.kind === "legal").map((r) => normPath(r.path));
+    const prefixes = [];
+    for (const p of set) {
+        if (p.startsWith("/*/")) {
+            prefixes.push(p);
+            continue;
+        }
+        if (publicPaths.some((pp) => pp === p || pp.startsWith(p + "/")))
+            conflicts.push(p);
+        else
+            prefixes.push(p);
+    }
+    return { prefixes: prefixes.sort(), conflicts, defaulted };
+}
+export function appPathsText(scan, extra = []) {
+    const a = appPrefixes(scan, extra);
+    if (!a.prefixes.length)
+        return scan ? "none found by the scan — close only real app/API paths" : DEFAULT_APP_PREFIXES.map((p) => p + "/").join(", ");
+    return a.prefixes.map((p) => p + "/").join(", ");
+}
+/** Login, sign-up, checkout, thank-you and search routes: noindex,follow (and not Disallowed). */
+export function noindexRoutes(scan, closed = []) {
+    const out = [];
+    for (const r of scan?.routes ?? []) {
+        if (r.kind !== "auth" && r.kind !== "checkout" && r.kind !== "search")
+            continue;
+        const p = normPath(r.path);
+        if (closed.some((c) => !c.startsWith("/*/") && (p === c || p.startsWith(c + "/"))))
+            continue;
+        out.push(r.path);
+    }
+    return [...new Set(out)];
+}
+export const PAGE_PATTERNS = {
+    pricing: /\/(pricing|prices|plans|fiyat\w*|precios|preise|tarifs?|prezzi|precos|tarifler)(\/|$)/,
+    faq: /\/(faq|faqs|sss|help|questions|frequently-asked-questions|sikca-sorulan-sorular)(\/|$)/,
+    about: /\/(about|about-us|hakkimizda|hakkinda|company|team|uber-uns|a-propos|chi-siamo|quienes-somos|sobre)(\/|$)/,
+    contact: /\/(contact|contact-us|iletisim|kontakt|contacto|contatti)(\/|$)/,
+    privacy: /\/(privacy|privacy-policy|gizlilik\w*|kvkk|datenschutz|privacidad)(\/|$)/,
+    terms: /\/(terms|tos|terms-of-service|terms-and-conditions|sartlar|kosullar|kullanim-kosullari|agb)(\/|$)/,
+    comparison: /(\/(compare|comparison|alternatives?|vs|versus|karsilastirma|alternatif\w*)(\/|-|$))|-vs-|\/best-/,
+    guide: /\/(guides?|rehber\w*|blog|learn|resources|articles?)(\/|$)/,
+    glossary: /\/(glossary|sozluk)(\/|$)/,
+};
+/** Known public paths: scan routes that aren't app/auth/api + audit pages that returned 200. */
+export function knownPublicPaths(scan, audit) {
+    const m = new Map();
+    for (const r of scan?.routes ?? []) {
+        if (r.kind === "public" || r.kind === "legal" || r.kind === "unknown")
+            m.set(normPath(r.path), "scan");
+    }
+    for (const p of audit?.pages ?? []) {
+        if (p.status >= 200 && p.status < 300)
+            m.set(normPath(p.url), "live");
+    }
+    return m;
+}
+export function findPage(paths, key) {
+    if (key === "home") {
+        const s = paths.get("/");
+        return s ? { path: "/", source: s } : undefined;
+    }
+    const re = PAGE_PATTERNS[key];
+    let best;
+    for (const [p, source] of paths) {
+        if (!re.test(p) || /[[:*$]/.test(p))
+            continue;
+        if (!best || p.length < best.path.length || (source === "live" && best.source === "scan"))
+            best = { path: p, source };
+    }
+    return best;
+}
+export function pathKnown(paths, url) {
+    if (!url)
+        return undefined;
+    return paths.get(normPath(url));
+}

package/dist/tools/method/lib/state.js

@@ -0,0 +1,454 @@
+// Defensive readers for the .katman/ files other modules write (scan, audits, runs) and for plan/research.
+// Those files may be missing, partial or hand-edited: every reader returns a well-formed shape or undefined.
+import path from "node:path";
+import { existsSync, statSync, promises as fs } from "node:fs";
+import { KATMAN_DIR, katmanPath, listFiles, readJson } from "../../../state.js";
+import { domainOf } from "../../../util.js";
+const isObj = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+const arr = (x) => (Array.isArray(x) ? x : []);
+const str = (x) => (typeof x === "string" ? x : undefined);
+const num = (x, d = 0) => (typeof x === "number" && Number.isFinite(x) ? x : d);
+const bool = (x) => x === true;
+export function hasKatmanDir(root) {
+    return existsSync(path.join(root, KATMAN_DIR));
+}
+// ---------------------------------------------------------------------------
+// research
+export function normalizeResearch(raw) {
+    if (!isObj(raw))
+        return undefined;
+    const site = isObj(raw.site) ? raw.site : {};
+    const brand = isObj(raw.brand) ? raw.brand : {};
+    const url = str(site.url) ?? "";
+    const r = {
+        version: 1,
+        updatedAt: str(raw.updatedAt) ?? "",
+        site: {
+            url,
+            domain: str(site.domain) ?? (url && /^https?:/i.test(url) ? domainOf(url) : ""),
+            languages: arr(site.languages).filter((x) => typeof x === "string"),
+            ...(Array.isArray(site.previewUrls) ? { previewUrls: arr(site.previewUrls).filter((x) => typeof x === "string") } : {}),
+        },
+        brand: {
+            ...brand,
+            name: str(brand.name) ?? "",
+            category: str(brand.category) ?? "",
+        },
+        situations: arr(raw.situations)
+            .filter((s) => isObj(s) && typeof s.sentence === "string")
+            .map((s) => ({
+            id: str(s.id) ?? "",
+            sentence: String(s.sentence),
+            ...(str(s.url) ? { url: String(s.url) } : {}),
+            ...(s.status === "live" || s.status === "planned" ? { status: s.status } : {}),
+        })),
+        competitors: arr(raw.competitors)
+            .filter((c) => isObj(c) && typeof c.name === "string")
+            .map((c) => ({ ...c, name: String(c.name), url: str(c.url) ?? "" })),
+        proof: arr(raw.proof)
+            .filter((p) => isObj(p) && typeof p.claim === "string")
+            .map((p) => ({ ...p, claim: String(p.claim), source: str(p.source) ?? "" })),
+        keywords: arr(raw.keywords)
+            .filter((k) => isObj(k) && typeof k.term === "string")
+            .map((k) => k),
+        questions: arr(raw.questions)
+            .filter((q) => isObj(q) && typeof q.text === "string")
+            .map((q) => ({
+            id: str(q.id) ?? "",
+            type: (str(q.type) ?? "situation"),
+            text: String(q.text),
+            ...(str(q.lang) ? { lang: String(q.lang) } : {}),
+        })),
+    };
+    return r;
+}
+export async function loadResearchSafe(root) {
+    return normalizeResearch(await readJson(root, "research.json"));
+}
+export async function loadConfigSafe(root) {
+    const c = await readJson(root, "config.json");
+    return isObj(c) ? c : {};
+}
+// ---------------------------------------------------------------------------
+// scan.json
+function fileInfo(x) {
+    if (!isObj(x))
+        return { exists: false };
+    return { exists: bool(x.exists), ...(str(x.path) ? { path: str(x.path) } : {}), ...(x.generated === true ? { generated: true } : {}) };
+}
+export function normalizeFinding(x) {
+    if (!isObj(x) || typeof x.title !== "string")
+        return undefined;
+    const sev = ["critical", "high", "medium", "low", "info"].includes(String(x.severity)) ? x.severity : "medium";
+    const gate = ["read", "quote", "fit", "mention", "measure"].includes(String(x.gate)) ? x.gate : "read";
+    const prompt = /^P([0-9]|1[0-4])$/.test(String(x.prompt)) ? x.prompt : undefined;
+    return {
+        id: str(x.id) ?? x.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40),
+        title: x.title,
+        severity: sev,
+        gate,
+        detail: str(x.detail) ?? "",
+        ...(Array.isArray(x.evidence) ? { evidence: arr(x.evidence).map(String) } : {}),
+        ...(Array.isArray(x.files) ? { files: arr(x.files).map(String) } : {}),
+        ...(Array.isArray(x.urls) ? { urls: arr(x.urls).map(String) } : {}),
+        ...(str(x.fix) ? { fix: str(x.fix) } : {}),
+        ...(prompt ? { prompt } : {}),
+        ...(str(x.accept) ? { accept: str(x.accept) } : {}),
+    };
+}
+export function normalizeScan(raw, root) {
+    if (!isObj(raw))
+        return undefined;
+    const fw = isObj(raw.framework) ? raw.framework : {};
+    const rend = isObj(raw.rendering) ? raw.rendering : {};
+    const host = isObj(raw.hosting) ? raw.hosting : {};
+    const files = isObj(raw.files) ? raw.files : {};
+    const i18n = isObj(raw.i18n) ? raw.i18n : {};
+    const an = isObj(raw.analytics) ? raw.analytics : {};
+    const verdicts = ["ssr", "ssg", "hybrid", "csr", "static-html", "unknown"];
+    const kinds = ["public", "app", "auth", "api", "legal", "checkout", "search", "unknown"];
+    return {
+        version: 1,
+        ts: str(raw.ts) ?? "",
+        root: str(raw.root) ?? root,
+        framework: {
+            name: str(fw.name) ?? "unknown",
+            ...(str(fw.version) ? { version: str(fw.version) } : {}),
+            ...(str(fw.router) ? { router: str(fw.router) } : {}),
+            ...(str(fw.builder) ? { builder: str(fw.builder) } : {}),
+        },
+        rendering: {
+            verdict: (verdicts.includes(String(rend.verdict)) ? rend.verdict : "unknown"),
+            confidence: (["high", "medium", "low"].includes(String(rend.confidence)) ? rend.confidence : "low"),
+            evidence: arr(rend.evidence).map(String),
+        },
+        hosting: {
+            ...(str(host.provider) ? { provider: str(host.provider) } : {}),
+            previewPatterns: arr(host.previewPatterns).map(String),
+            evidence: arr(host.evidence).map(String),
+        },
+        ...(typeof raw.staticDir === "string" ? { staticDir: raw.staticDir } : {}),
+        routes: arr(raw.routes)
+            .filter((r) => isObj(r) && typeof r.path === "string")
+            .map((r) => ({
+            path: String(r.path),
+            ...(str(r.file) ? { file: str(r.file) } : {}),
+            kind: (kinds.includes(String(r.kind)) ? r.kind : "unknown"),
+            dynamic: bool(r.dynamic) || /[[:*$]/.test(String(r.path)),
+        })),
+        files: {
+            robots: fileInfo(files.robots),
+            sitemap: fileInfo(files.sitemap),
+            llms: fileInfo(files.llms),
+            llmsFull: fileInfo(files.llmsFull),
+            notFound: fileInfo(files.notFound),
+            ...(isObj(files.headSource) ? { headSource: fileInfo(files.headSource) } : {}),
+        },
+        jsonLdTypes: arr(raw.jsonLdTypes).map(String),
+        i18n: {
+            detected: bool(i18n.detected),
+            ...(str(i18n.library) ? { library: str(i18n.library) } : {}),
+            locales: arr(i18n.locales).map(String),
+            ...(str(i18n.htmlLang) ? { htmlLang: str(i18n.htmlLang) } : {}),
+        },
+        analytics: { providers: arr(an.providers).map(String), tracksAiChannel: bool(an.tracksAiChannel) },
+        findings: arr(raw.findings).map(normalizeFinding).filter((f) => !!f),
+        ...(Array.isArray(raw.domains) ? { domains: arr(raw.domains).filter((d) => typeof d === "string" && d.includes(".")) } : {}),
+    };
+}
+export async function loadScan(root) {
+    return normalizeScan(await readJson(root, "scan.json"), root);
+}
+// ---------------------------------------------------------------------------
+// audits/<stamp>.json
+function normalizePage(x) {
+    if (!isObj(x) || typeof x.url !== "string")
+        return undefined;
+    return {
+        url: x.url,
+        status: num(x.status),
+        ...(str(x.contentType) ? { contentType: str(x.contentType) } : {}),
+        noindex: bool(x.noindex),
+        ...(str(x.title) !== undefined ? { title: str(x.title) } : {}),
+        ...(str(x.description) !== undefined ? { description: str(x.description) } : {}),
+        ...(str(x.canonical) ? { canonical: str(x.canonical) } : {}),
+        ...(typeof x.canonicalSelf === "boolean" ? { canonicalSelf: x.canonicalSelf } : {}),
+        h1Count: num(x.h1Count),
+        headingSkips: num(x.headingSkips),
+        wordsJsOff: num(x.wordsJsOff),
+        ...(str(x.firstParagraph) ? { firstParagraph: str(x.firstParagraph) } : {}),
+        jsonLdTypes: arr(x.jsonLdTypes).map(String),
+        jsonLdErrors: num(x.jsonLdErrors),
+        ...(str(x.ogImage) ? { ogImage: str(x.ogImage) } : {}),
+        ...(str(x.lang) ? { lang: str(x.lang) } : {}),
+        hreflang: arr(x.hreflang).filter(isObj).map((h) => ({ lang: String(h.lang ?? ""), href: String(h.href ?? "") })),
+        imagesMissingAlt: num(x.imagesMissingAlt),
+        internalLinksOut: num(x.internalLinksOut),
+        internalLinksIn: num(x.internalLinksIn),
+        inSitemap: bool(x.inSitemap),
+        ...(str(x.dateModified) ? { dateModified: str(x.dateModified) } : {}),
+        bytes: num(x.bytes),
+        ms: num(x.ms),
+    };
+}
+function gate(x) {
+    if (!isObj(x))
+        return { pass: 0, total: 0, notes: [] };
+    return { pass: num(x.pass), total: num(x.total), notes: arr(x.notes).map(String) };
+}
+export function normalizeAudit(raw) {
+    if (!isObj(raw))
+        return undefined;
+    const site = isObj(raw.site) ? raw.site : {};
+    const robots = isObj(site.robots) ? site.robots : {};
+    const llms = isObj(site.llmsTxt) ? site.llmsTxt : {};
+    const gates = isObj(raw.gates) ? raw.gates : {};
+    return {
+        version: 1,
+        ts: str(raw.ts) ?? "",
+        siteUrl: str(raw.siteUrl) ?? "",
+        pages: arr(raw.pages).map(normalizePage).filter((p) => !!p),
+        site: {
+            ...(typeof site.httpsRedirect === "boolean" ? { httpsRedirect: site.httpsRedirect } : {}),
+            ...(typeof site.hostRedirect === "boolean" ? { hostRedirect: site.hostRedirect } : {}),
+            ...(typeof site.hsts === "boolean" ? { hsts: site.hsts } : {}),
+            ...(site.compression !== undefined ? { compression: (str(site.compression) ?? null) } : {}),
+            ...(typeof site.soft404 === "boolean" ? { soft404: site.soft404 } : {}),
+            llmsTxt: { exists: bool(llms.exists), ...(typeof llms.bytes === "number" ? { bytes: llms.bytes } : {}) },
+            robots: {
+                exists: bool(robots.exists),
+                sitemaps: arr(robots.sitemaps).map(String),
+                blocksAll: bool(robots.blocksAll),
+                blockedAiTokens: arr(robots.blockedAiTokens).map(String),
+                invalidLines: arr(robots.invalidLines).map(String),
+            },
+            sitemapUrls: num(site.sitemapUrls),
+            ...(str(site.cdn) ? { cdn: str(site.cdn) } : {}),
+            bots: arr(site.bots)
+                .filter(isObj)
+                .map((b) => ({
+                token: String(b.token ?? ""),
+                purpose: String(b.purpose ?? ""),
+                status: num(b.status),
+                blocked: bool(b.blocked),
+                ...(str(b.reason) ? { reason: str(b.reason) } : {}),
+            })),
+        },
+        gates: { read: gate(gates.read), quote: gate(gates.quote), fit: gate(gates.fit) },
+        findings: arr(raw.findings).map(normalizeFinding).filter((f) => !!f),
+    };
+}
+/** Latest audit by file name (stamps sort chronologically). Skips files that don't parse. */
+export async function loadLatestAudit(root) {
+    const names = (await listFiles(root, "audits")).filter((n) => n.endsWith(".json"));
+    for (let i = names.length - 1; i >= 0; i--) {
+        const a = normalizeAudit(await readJson(root, path.join("audits", names[i])));
+        if (a)
+            return { audit: a, file: names[i], count: names.length };
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// runs/<stamp>.json
+function normalizeAnswer(x) {
+    if (!isObj(x))
+        return undefined;
+    return {
+        questionId: String(x.questionId ?? ""),
+        question: String(x.question ?? ""),
+        questionType: (str(x.questionType) ?? "situation"),
+        model: String(x.model ?? ""),
+        family: String(x.family ?? x.model ?? ""),
+        source: x.source === "manual" ? "manual" : "api",
+        ...(str(x.surface) ? { surface: str(x.surface) } : {}),
+        ts: String(x.ts ?? ""),
+        ...(typeof x.temperature === "number" ? { temperature: x.temperature } : {}),
+        mentioned: bool(x.mentioned),
+        recommendedFirst: bool(x.recommendedFirst),
+        rank: typeof x.rank === "number" ? x.rank : null,
+        cited: bool(x.cited),
+        namedProducts: arr(x.namedProducts).map(String),
+        competitorsNamed: arr(x.competitorsNamed).map(String),
+        citations: arr(x.citations)
+            .filter(isObj)
+            .map((c) => ({ url: String(c.url ?? ""), ...(str(c.title) ? { title: str(c.title) } : {}), domain: String(c.domain ?? domainOf(String(c.url ?? ""))) })),
+        answerExcerpt: String(x.answerExcerpt ?? ""),
+        ...(typeof x.identityCorrect === "boolean" || x.identityCorrect === null ? { identityCorrect: x.identityCorrect } : {}),
+        ...(typeof x.costUsd === "number" ? { costUsd: x.costUsd } : {}),
+        ...(str(x.error) ? { error: str(x.error) } : {}),
+        ...(typeof x.searched === "boolean" ? { searched: x.searched } : {}),
+        ...(typeof x.sample === "number" ? { sample: x.sample } : {}),
+        ...(str(x.lang) ? { lang: str(x.lang) } : {}),
+    };
+}
+/** Recompute the summary from answers (used when a run file has none or a partial one). */
+export function summarizeAnswers(answers) {
+    const ok = answers.filter((a) => !a.error);
+    const byFamily = {};
+    const byLanguage = {};
+    const comp = new Map();
+    const doms = new Map();
+    for (const a of ok) {
+        const buckets = [(byFamily[a.family || a.model] ??= { answered: 0, mentioned: 0, recommendedFirst: 0, cited: 0 })];
+        if (a.lang)
+            buckets.push((byLanguage[a.lang] ??= { answered: 0, mentioned: 0, recommendedFirst: 0, cited: 0 }));
+        for (const f of buckets) {
+            f.answered++;
+            if (a.mentioned)
+                f.mentioned++;
+            if (a.recommendedFirst)
+                f.recommendedFirst++;
+            if (a.cited)
+                f.cited++;
+        }
+        for (const c of a.competitorsNamed)
+            comp.set(c, (comp.get(c) ?? 0) + 1);
+        for (const c of a.citations)
+            if (c.domain)
+                doms.set(c.domain, (doms.get(c.domain) ?? 0) + 1);
+    }
+    const n = ok.length || 1;
+    const top = (m) => [...m.entries()].sort((a, b) => b[1] - a[1]).slice(0, 15);
+    return {
+        answered: ok.length,
+        mentionRate: ok.filter((a) => a.mentioned).length / n,
+        recommendedFirstRate: ok.filter((a) => a.recommendedFirst).length / n,
+        citationRate: ok.filter((a) => a.cited).length / n,
+        byFamily,
+        topCompetitors: top(comp).map(([name, count]) => ({ name, count })),
+        topCitedDomains: top(doms).map(([domain, count]) => ({ domain, count })),
+        ...(Object.keys(byLanguage).length ? { byLanguage } : {}),
+    };
+}
+export function normalizeRun(raw, fallbackId) {
+    if (!isObj(raw))
+        return undefined;
+    const answers = arr(raw.answers).map(normalizeAnswer).filter((a) => !!a);
+    const s = isObj(raw.summary) ? raw.summary : undefined;
+    const computed = summarizeAnswers(answers);
+    const summary = s
+        ? {
+            answered: typeof s.answered === "number" ? s.answered : computed.answered,
+            mentionRate: typeof s.mentionRate === "number" ? s.mentionRate : computed.mentionRate,
+            recommendedFirstRate: typeof s.recommendedFirstRate === "number" ? s.recommendedFirstRate : computed.recommendedFirstRate,
+            citationRate: typeof s.citationRate === "number" ? s.citationRate : computed.citationRate,
+            byFamily: isObj(s.byFamily) ? s.byFamily : computed.byFamily,
+            topCompetitors: Array.isArray(s.topCompetitors) ? s.topCompetitors : computed.topCompetitors,
+            topCitedDomains: Array.isArray(s.topCitedDomains) ? s.topCitedDomains : computed.topCitedDomains,
+            ...(isObj(s.byLanguage)
+                ? { byLanguage: s.byLanguage }
+                : computed.byLanguage
+                    ? { byLanguage: computed.byLanguage }
+                    : {}),
+        }
+        : computed;
+    return {
+        id: str(raw.id) ?? fallbackId,
+        ts: str(raw.ts) ?? "",
+        brand: String(raw.brand ?? ""),
+        domain: String(raw.domain ?? ""),
+        models: arr(raw.models)
+            .filter(isObj)
+            .map((m) => ({ id: String(m.id ?? ""), family: String(m.family ?? m.id ?? ""), search: (["native", "plugin", "none"].includes(String(m.search)) ? m.search : "none") })),
+        temperature: typeof raw.temperature === "number" ? raw.temperature : null,
+        ...(raw.status === "complete" || raw.status === "partial" ? { status: raw.status } : {}),
+        answers,
+        summary,
+        ...(typeof raw.totalCostUsd === "number" ? { totalCostUsd: raw.totalCostUsd } : {}),
+    };
+}
+/** All runs, oldest first. */
+export async function loadRuns(root) {
+    const names = (await listFiles(root, "runs")).filter((n) => n.endsWith(".json"));
+    const out = [];
+    for (const n of names) {
+        const r = normalizeRun(await readJson(root, path.join("runs", n)), n.replace(/\.json$/, ""));
+        if (r)
+            out.push(r);
+    }
+    return out.sort((a, b) => (a.ts || a.id).localeCompare(b.ts || b.id));
+}
+export function runDate(r) {
+    const d = new Date(r.ts);
+    if (!Number.isNaN(d.getTime()))
+        return d;
+    const m = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})Z/.exec(r.id);
+    if (m)
+        return new Date(`${m[1]}T${m[2]}:${m[3]}:${m[4]}Z`);
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// project files (read-only, never secrets)
+const SECRET_RE = /(^|[\\/])(\.env[^\\/]*|\.dev\.vars[^\\/]*)$|\.(pem|key|p12|pfx)$|secret|credential/i;
+export function isSecretPath(p) {
+    return SECRET_RE.test(p);
+}
+/** Resolve a path relative to the project root; undefined when it escapes the root. */
+export function insideRoot(root, rel) {
+    const base = path.resolve(root);
+    const p = path.resolve(base, rel);
+    if (p !== base && !p.startsWith(base + path.sep))
+        return undefined;
+    return p;
+}
+export async function readProjectFile(root, rel, maxBytes = 2_000_000) {
+    const abs = insideRoot(root, rel);
+    if (!abs)
+        return { error: `${rel} is outside the project root ${root}.` };
+    if (isSecretPath(abs))
+        return { error: `Katman never reads secret files (${path.basename(abs)}).` };
+    try {
+        const st = await fs.stat(abs);
+        if (!st.isFile())
+            return { abs, error: `${rel} is not a file.` };
+        if (st.size > maxBytes)
+            return { abs, error: `${rel} is larger than ${Math.round(maxBytes / 1e6)} MB.` };
+        return { abs, text: await fs.readFile(abs, "utf8") };
+    }
+    catch {
+        return { abs, error: `${rel} not found.` };
+    }
+}
+export async function mtimeOf(p) {
+    try {
+        return (await fs.stat(p)).mtime;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function katmanMtime(root, rel) {
+    return mtimeOf(katmanPath(root, rel));
+}
+// ---------------------------------------------------------------------------
+// static dir (folder served as-is at the site root)
+const STATIC_BY_FRAMEWORK = {
+    sveltekit: "static", hugo: "static", gatsby: "static", jekyll: "", eleventy: "", "static-html": "",
+};
+export function cleanRel(p) {
+    const s = p.replace(/\\/g, "/").replace(/^\.\/?/, "").replace(/\/+$/, "");
+    return s === "." ? "" : s;
+}
+/** scan.staticDir → existing public/ or static/ → framework convention → project root. */
+export function staticDirFor(root, scan) {
+    if (scan && typeof scan.staticDir === "string")
+        return { dir: cleanRel(scan.staticDir), source: "scan" };
+    for (const d of ["public", "static"]) {
+        try {
+            if (statSync(path.join(root, d)).isDirectory())
+                return { dir: d, source: "detected" };
+        }
+        catch {
+            // not there
+        }
+    }
+    const name = scan?.framework.name ?? "";
+    if (name in STATIC_BY_FRAMEWORK)
+        return { dir: STATIC_BY_FRAMEWORK[name], source: "convention" };
+    if (name && name !== "unknown")
+        return { dir: "public", source: "convention" };
+    return { dir: "", source: "root" };
+}
+export function joinRel(...parts) {
+    return parts.filter((p) => p !== "").join("/").replace(/\/+/g, "/");
+}