@bcelep/capint 0.4.2 → 0.7.0

package/src/lib/doctor.js

@@ -1,7 +1,9 @@
 const fs = require("fs");
 const path = require("path");
 const { loadMatrix } = require("./route-engine");
-const { validateExecutionIntent } = require("./contract");
+const { loadDisabledSkills } = require("./disabled-skills");
+const { listBackups } = require("./recover");
+const { resolveLocale, t } = require("./i18n");
 
 function loadRegistry(rootDir) {
   const p = path.join(rootDir, "registry.json");
@@ -21,7 +23,60 @@ function skillsOnDisk(rootDir) {
     .filter((n) => fs.existsSync(path.join(skillsDir, n, "SKILL.md")));
 }
 
-function runDoctor(rootDir) {
+function buildDoctorActions({ issues, warnings, rootDir, locale }) {
+  const loc = resolveLocale(locale);
+  const actions = [];
+  const hasConfigIssue = issues.some(
+    (i) => i.includes("matrix") || i.includes("registry") || i.includes("parse error")
+  );
+  const { groups } = listBackups(rootDir);
+
+  if (hasConfigIssue && groups.length) {
+    actions.push({
+      id: "recover_latest",
+      safe: true,
+      command: "capint recover --latest --apply",
+      label_tr: t("ui.recover.apply", "tr"),
+      label_en: t("ui.recover.apply", "en"),
+      label: t("ui.recover.apply", loc)
+    });
+  }
+
+  for (const w of warnings) {
+    const m = w.match(/^core skill disabled: (\S+)/);
+    if (m) {
+      actions.push({
+        id: "enable_core",
+        safe: true,
+        skill: m[1],
+        command: `capint skill enable ${m[1]}`,
+        label_tr: `Core skill'i aç: ${m[1]}`,
+        label_en: `Re-enable core skill: ${m[1]}`,
+        label: loc === "en" ? `Re-enable core skill: ${m[1]}` : `Core skill'i aç: ${m[1]}`
+      });
+    }
+  }
+
+  return actions;
+}
+
+function buildSummaryPlain({ pass, issues, warnings, locale }) {
+  const loc = resolveLocale(locale);
+  if (pass && !warnings.length) return t("doctor.summary.ok", loc);
+  if (issues.some((i) => i.includes("matrix") || i.includes("registry"))) {
+    return t("doctor.summary.registry", loc);
+  }
+  if (warnings.some((w) => w.includes("disabled"))) {
+    return t("doctor.summary.disabled", loc);
+  }
+  if (!pass) {
+    return loc === "en" ? "Configuration issues found — see details below." : "Yapılandırma sorunları var — aşağıdaki detaylara bak.";
+  }
+  return loc === "en" ? "Healthy with minor warnings." : "Genel olarak sağlıklı; küçük uyarılar var.";
+}
+
+function runDoctor(rootDir, options = {}) {
+  const locale = resolveLocale(options.locale);
   const issues = [];
   const warnings = [];
   const ok = [];
@@ -43,6 +98,11 @@ function runDoctor(rootDir) {
       ...(registry.optional || []),
       ...(registry.project_added || [])
     ]);
+    for (const name of disk) {
+      if (!allReg.has(name)) {
+        warnings.push(`Skill on disk but not in registry: ${name}`);
+      }
+    }
     for (const name of registry.core || []) {
       if (!disk.has(name)) warnings.push(`core skill missing on disk: ${name}`);
     }
@@ -61,6 +121,27 @@ function runDoctor(rootDir) {
     warnings.push("AGENT.md missing — run capint init");
   }
 
+  const disabledOverlay = loadDisabledSkills(rootDir);
+  if (disabledOverlay.parseError) {
+    warnings.push(`.capint/disabled-skills.json invalid — fix JSON or delete file`);
+  }
+  if (registry && !registry.parseError && disabledOverlay.disabled?.length) {
+    for (const name of disabledOverlay.disabled) {
+      if ((registry.core || []).includes(name)) {
+        warnings.push(`core skill disabled: ${name} — capint skill enable ${name}`);
+      }
+    }
+  }
+
+  if (registry && !registry.parseError && registry.project_added?.length) {
+    const disk = new Set(skillsOnDisk(rootDir));
+    for (const name of registry.project_added) {
+      if (!disk.has(name)) {
+        warnings.push(`pinned skill missing on disk: ${name}`);
+      }
+    }
+  }
+
   const policy = matrix?.provider_activation_policy;
   if (policy) {
     ok.push("provider_activation_policy present (default off)");
@@ -69,6 +150,18 @@ function runDoctor(rootDir) {
   }
 
   const pass = issues.length === 0;
+  let hint = pass ? "No auto-fix performed (by design)." : "Resolve issues manually; doctor does not mutate files.";
+  if (!pass) {
+    if (issues.some((i) => i.includes("matrix") || i.includes("registry"))) {
+      hint = "Try: capint recover --list then capint recover --latest --apply";
+    }
+  } else if (warnings.some((w) => w.includes("disabled"))) {
+    hint = "Re-enable core skills: capint skill enable <name>";
+  }
+
+  const actions = buildDoctorActions({ issues, warnings, rootDir, locale });
+  const summary_plain = buildSummaryPlain({ pass, issues, warnings, locale });
+
   return {
     pass,
     exit_code: pass ? 0 : 1,
@@ -76,7 +169,11 @@ function runDoctor(rootDir) {
     warnings,
     ok,
     auto_fix: false,
-    hint: pass ? "No auto-fix performed (by design)." : "Resolve issues manually; doctor does not mutate files."
+    hint,
+    actions,
+    summary_plain,
+    summary_plain_tr: buildSummaryPlain({ pass, issues, warnings, locale: "tr" }),
+    summary_plain_en: buildSummaryPlain({ pass, issues, warnings, locale: "en" })
   };
 }
 

package/src/lib/env-flags.js

@@ -0,0 +1,35 @@
+const CONFIRM_OPTIONS = new Set(["apply_now", "plan_first", "analyze_only"]);
+
+function envFlag(name) {
+  const v = process.env[name];
+  if (v === undefined || v === "") return null;
+  return v;
+}
+
+function isDebugEnabled() {
+  const v = envFlag("CAPINT_DEBUG");
+  return v === "1" || v === "true";
+}
+
+function defaultConfirmOverride() {
+  const v = envFlag("CAPINT_DEFAULT_CONFIRM");
+  if (!v) return null;
+  const normalized = v.trim().toLowerCase();
+  if (!CONFIRM_OPTIONS.has(normalized)) return null;
+  return normalized;
+}
+
+function logDebug(rootDir, payload) {
+  if (!isDebugEnabled()) return;
+  const extra = rootDir
+    ? { disabled_overlay: require("./disabled-skills").disabledSet(rootDir).size }
+    : {};
+  console.error("[capint debug]", JSON.stringify({ ...payload, ...extra }, null, 0));
+}
+
+module.exports = {
+  CONFIRM_OPTIONS,
+  isDebugEnabled,
+  defaultConfirmOverride,
+  logDebug
+};

package/src/lib/execution-policy.js

@@ -1,6 +1,12 @@
 const fs = require("fs");
 const path = require("path");
 const { resolveOrchestration } = require("./orchestration");
+const { disabledSet, overlayParseError } = require("./disabled-skills");
+const { buildExplanation } = require("./explanation");
+const { resolveLocale } = require("./i18n");
+const { matchKeywords } = require("./intent-parser");
+const { defaultConfirmOverride } = require("./env-flags");
+const { detectWorkspaceBoundary } = require("./workspace-boundary");
 
 function resolveInstallationStatus(routeResult, rootDir) {
   const winner = routeResult.winner;
@@ -8,13 +14,24 @@ function resolveInstallationStatus(routeResult, rootDir) {
     return { resolution_status: "installed", resolution_hint: null };
   }
 
+  const disabled = rootDir ? disabledSet(rootDir) : new Set();
+
   if (winner.type === "skill") {
+    if (disabled.has(winner.resource)) {
+      return {
+        resolution_status: "not_installed",
+        resolution_hint: `Skill "${winner.resource}" disabled — run capint skill enable ${winner.resource}`
+      };
+    }
     const allSkills = routeResult.rows.flatMap((r) => r.skills);
     const match = allSkills.find((s) => s.name === winner.resource);
-    if (match?.status === "not_installed") {
+    if (match?.status === "not_installed" || match?.status === "disabled") {
       return {
         resolution_status: "not_installed",
-        resolution_hint: `Skill "${winner.resource}" not installed — run capint init or add skills/${winner.resource}/SKILL.md`
+        resolution_hint:
+          match?.status === "disabled"
+            ? `Skill "${winner.resource}" disabled — run capint skill enable ${winner.resource}`
+            : `Skill "${winner.resource}" not installed — run capint init or add skills/${winner.resource}/SKILL.md`
       };
     }
   }
@@ -45,7 +62,11 @@ function buildConfirmBlock(text, overallWeight, matrix) {
   ];
   const maxOptions = Math.max(1, Math.min(policy.max_options || 3, options.length));
   const shortened = options.slice(0, maxOptions);
-  const defaultOption = policy.default_option || (overallWeight === "light" ? "apply_now" : "plan_first");
+  let defaultOption = policy.default_option || (overallWeight === "light" ? "apply_now" : "plan_first");
+  const envDefault = defaultConfirmOverride();
+  if (envDefault && shortened.some((o) => o.id === envDefault)) {
+    defaultOption = envDefault;
+  }
   return {
     enabled: true,
     mode,
@@ -110,11 +131,37 @@ function buildExecutionPolicy({ rawText, routeResult, memoryStrategy, matrix, pa
   if (installStatus.resolution_status === "not_installed") {
     plan = "confirm";
   }
-  const confirmBlock = buildConfirmBlock(rawText, overallWeight, matrix);
+  const boundary = detectWorkspaceBoundary(rawText);
+  const overlayCorrupt = rootDir ? overlayParseError(rootDir) : false;
+  let confirmBlock = buildConfirmBlock(rawText, overallWeight, matrix);
+  if (!confirmBlock.enabled) {
+    plan = "auto";
+  }
+  if (boundary.violated) {
+    plan = "override";
+    confirmBlock = {
+      enabled: false,
+      mode: "blocked",
+      prompt: null,
+      options: [],
+      default_option: null
+    };
+  }
   const ambiguous = rows.some((r) => r.reason.includes("ambiguous default"));
   const verification = buildVerificationHints(overallWeight, primaryTaskType, matrix);
   const orchestration = resolveOrchestration(primaryTaskType, confirmBlock.default_option, matrix);
 
+  const explanation = buildExplanation({
+    text: rawText,
+    routeResult,
+    matrix,
+    rootDir,
+    matchKeywords,
+    resolutionStatus: installStatus.resolution_status,
+    confirmDefaultOption: confirmBlock.default_option,
+    locale: resolveLocale()
+  });
+
   const out = {
     intent: rawText,
     capability,
@@ -133,6 +180,7 @@ function buildExecutionPolicy({ rawText, routeResult, memoryStrategy, matrix, pa
     context_pack: memoryStrategy?.context_pack || null,
     orchestration,
     route_explain: buildRouteExplain(routeResult, parsedIntent, matrix),
+    explanation,
     resolution_status: installStatus.resolution_status,
     resolution_hint: installStatus.resolution_hint
   };
@@ -156,6 +204,34 @@ function buildExecutionPolicy({ rawText, routeResult, memoryStrategy, matrix, pa
     ];
   }
 
+  if (boundary.violated) {
+    out.workspace_boundary = {
+      violated: true,
+      suspicious_paths: boundary.suspicious_paths,
+      override_hint: boundary.override_hint
+    };
+    out.verification_required = true;
+    out.verification_hints = [
+      ...(out.verification_hints || []),
+      "Refuse file edits outside workspace until user adds cross-repo override phrase"
+    ];
+  }
+
+  if (overlayCorrupt) {
+    out.overlay_error = {
+      file: ".capint/disabled-skills.json",
+      hint: "Fix or remove corrupt disabled-skills overlay — routing fail-closed until repaired"
+    };
+    out.resolution_status = "not_installed";
+    out.resolution_hint =
+      "Corrupt .capint/disabled-skills.json — fix JSON or remove file, then capint doctor";
+    out.verification_required = true;
+    out.verification_hints = [
+      ...(out.verification_hints || []),
+      "disabled-skills overlay corrupt; all skills treated as disabled until fixed"
+    ];
+  }
+
   return out;
 }
 

package/src/lib/explanation-plain.js

@@ -0,0 +1,72 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveLocale, t } = require("./i18n");
+
+const TASK_LABELS = {
+  tr: {
+    write_prd: "PRD / ürün gereksinim belgesi yazımı",
+    spec_authoring: "teknik spec / dokümantasyon",
+    debug: "hata ayıklama",
+    refactor: "kod sadeleştirme / refactor",
+    localization: "çeviri / dil dosyaları",
+    default: "görev sınıflandırması"
+  },
+  en: {
+    write_prd: "PRD / product requirements writing",
+    spec_authoring: "technical spec / documentation",
+    debug: "debugging",
+    refactor: "refactoring / simplification",
+    localization: "translation / locale files",
+    default: "task classification"
+  }
+};
+
+function taskLabel(taskTypeId, locale) {
+  const loc = locale === "en" ? "en" : "tr";
+  const map = TASK_LABELS[loc];
+  if (!taskTypeId) return map.default;
+  if (taskTypeId.includes("prd") || taskTypeId === "write_prd") return map.write_prd;
+  if (taskTypeId.includes("spec") || taskTypeId.includes("author")) return map.spec_authoring;
+  if (taskTypeId.includes("debug")) return map.debug;
+  if (taskTypeId.includes("refactor")) return map.refactor;
+  if (taskTypeId.includes("i18n") || taskTypeId.includes("local")) return map.localization;
+  return map.default;
+}
+
+function buildTooltip({ taskType, winner, locale }) {
+  const loc = resolveLocale(locale);
+  if (taskType?.id?.includes("prd") || winner?.resource === "prd") {
+    return t("term.prd", loc);
+  }
+  if (winner?.type === "skill") {
+    return t("term.installed", loc);
+  }
+  return null;
+}
+
+function buildReasonPlain({ taskType, matched, winner, resolutionStatus, locale }) {
+  const loc = resolveLocale(locale);
+  const label = taskLabel(taskType?.id, loc);
+  const cap = winner?.resource || winner?.type || "capability-router";
+
+  if (resolutionStatus === "not_installed" && winner?.resource) {
+    if (loc === "en") {
+      return `The route picked ${cap}, but that skill is not available on disk or is disabled.`;
+    }
+    return `Seçilen yetenek (${cap}) diskte yok veya devre dışı.`;
+  }
+
+  const kw = matched.length ? matched.join(", ") : null;
+  if (loc === "en") {
+    if (kw) {
+      return `This looks like ${label} (keywords: ${kw}). Selected: ${cap}.`;
+    }
+    return `This looks like ${label}. Selected: ${cap}.`;
+  }
+  if (kw) {
+    return `Görevin ${label} gibi görünüyor (anahtar kelimeler: ${kw}). Seçilen: ${cap}.`;
+  }
+  return `Görevin ${label} gibi görünüyor. Seçilen: ${cap}.`;
+}
+
+module.exports = { buildReasonPlain, buildTooltip, taskLabel };

package/src/lib/explanation.js

@@ -0,0 +1,183 @@
+const fs = require("fs");
+const path = require("path");
+const { detectWorkspaceBoundary } = require("./workspace-boundary");
+const { resolveLocale } = require("./i18n");
+const { buildReasonPlain, buildTooltip } = require("./explanation-plain");
+
+const GATEWAY_SKILL = "prismx-skill-gateway";
+
+function matchedKeywords(text, taskType, matchKeywords) {
+  if (!taskType?.keywords?.length) return [];
+  return taskType.keywords.filter((kw) => matchKeywords(text, [kw]));
+}
+
+function filesToRead({ taskType, winner, rootDir }) {
+  const files = [];
+  const add = (rel) => {
+    const norm = rel.replace(/\\/g, "/");
+    if (!files.includes(norm)) files.push(norm);
+  };
+
+  add(`skills/${GATEWAY_SKILL}/SKILL.md`);
+
+  if (taskType?.skills?.length) {
+    for (const name of taskType.skills) {
+      add(`skills/${name}/SKILL.md`);
+    }
+  }
+
+  if (winner?.type === "skill" && winner.resource) {
+    add(`skills/${winner.resource}/SKILL.md`);
+  }
+
+  const workflowName =
+    winner?.type === "workflow"
+      ? winner.resource
+      : taskType?.workflow
+        ? String(taskType.workflow).replace(/^\//, "")
+        : null;
+
+  if (workflowName && rootDir) {
+    const wfPath = path.join(rootDir, "workflows", `${workflowName}.md`);
+    if (fs.existsSync(wfPath)) add(`workflows/${workflowName}.md`);
+  }
+
+  return files.slice(0, 8);
+}
+
+function buildAlternatives(taskType, winner) {
+  if (!taskType?.providers?.length) return [];
+  return [...taskType.providers]
+    .sort((a, b) => (b.confidence_base || 0) - (a.confidence_base || 0))
+    .filter((p) => !(p.type === winner?.type && p.resource === winner?.resource))
+    .slice(0, 4)
+    .map((p) => ({
+      resource: p.resource,
+      type: p.type,
+      confidence: p.confidence_base ?? null
+    }));
+}
+
+function buildReasonSummary({ taskType, matched, winner, resolutionStatus }) {
+  if (resolutionStatus === "not_installed" && winner?.resource) {
+    return `Route selected ${winner.type}/${winner.resource} but it is not available on disk or is disabled.`;
+  }
+  if (taskType?.id) {
+    const kw = matched.length ? matched.join(", ") : "task classification";
+    return `Matched task_type "${taskType.id}" via keywords [${kw}]; winner ${winner?.type}/${winner?.resource}.`;
+  }
+  return `Default routing; winner ${winner?.type}/${winner?.resource}.`;
+}
+
+function extractFilesIntended(text) {
+  const patterns = [
+    /(?:^|[\s'"`])([\w.-]+(?:[\\/][\w.-]+)+\.(?:js|ts|tsx|jsx|mjs|cjs|json|md|php|py|go|rs|css|html|yaml|yml|toml|vue|svelte))/gi,
+    /(?:^|[\s'"`])(src[\\/][^\s'"`,]+)/gi
+  ];
+  const found = [];
+  for (const re of patterns) {
+    for (const m of text.matchAll(re)) {
+      const p = m[1].replace(/\\/g, "/");
+      if (!found.includes(p) && !p.startsWith("http")) found.push(p);
+    }
+  }
+  return found.slice(0, 8);
+}
+
+function buildExplanation({
+  text,
+  routeResult,
+  matrix,
+  rootDir,
+  matchKeywords,
+  resolutionStatus,
+  confirmDefaultOption,
+  locale
+}) {
+  const resolvedLocale = resolveLocale(locale);
+  const taskType = routeResult.taskTypeResolved;
+  const winner = routeResult.winner
+    ? { type: routeResult.winner.type, resource: routeResult.winner.resource }
+    : null;
+
+  const matched = matchedKeywords(text, taskType, matchKeywords);
+  const boundary = detectWorkspaceBoundary(text);
+  const filesIntended =
+    confirmDefaultOption === "plan_first" || boundary.violated ? extractFilesIntended(text) : [];
+
+  const explanation = {
+    task_type_id: taskType?.id || null,
+    matched_keywords: matched,
+    winner,
+    files_to_read: filesToRead({ taskType, winner, rootDir }),
+    reason_summary: buildReasonSummary({ taskType, matched, winner, resolutionStatus }),
+    reason_plain: buildReasonPlain({
+      taskType,
+      matched,
+      winner,
+      resolutionStatus,
+      locale: resolvedLocale
+    }),
+    tooltip: buildTooltip({ taskType, winner, locale: resolvedLocale }),
+    locale: resolvedLocale,
+    alternatives_considered: buildAlternatives(taskType, winner),
+    resolver_order: matrix?.resolver_order || []
+  };
+
+  if (filesIntended.length) {
+    explanation.files_intended = filesIntended;
+  }
+  if (boundary.violated || boundary.suspicious_paths.length) {
+    explanation.workspace_boundary = {
+      violated: boundary.violated,
+      suspicious_paths: boundary.suspicious_paths,
+      override_hint: boundary.override_hint
+    };
+  }
+
+  return explanation;
+}
+
+function formatExplanationCard(explanation) {
+  if (!explanation) return [];
+  const lines = [];
+  lines.push("");
+  lines.push("## Explanation");
+  lines.push("");
+  if (explanation.reason_plain) {
+    lines.push(`Why: ${explanation.reason_plain}`);
+  }
+  lines.push(`Technical: ${explanation.reason_summary}`);
+  if (explanation.task_type_id) {
+    lines.push(`Task type: ${explanation.task_type_id}`);
+  }
+  if (explanation.matched_keywords?.length) {
+    lines.push(`Keywords: ${explanation.matched_keywords.join(", ")}`);
+  }
+  if (explanation.winner) {
+    lines.push(`Winner: ${explanation.winner.type}/${explanation.winner.resource}`);
+  }
+  if (explanation.files_to_read?.length) {
+    lines.push("Read:");
+    for (const f of explanation.files_to_read) {
+      lines.push(`  - ${f}`);
+    }
+  }
+  if (explanation.files_intended?.length) {
+    lines.push("Intended edits:");
+    for (const f of explanation.files_intended) {
+      lines.push(`  - ${f}`);
+    }
+  }
+  if (explanation.workspace_boundary?.violated) {
+    lines.push(`Boundary: refuse edits outside workspace — ${explanation.workspace_boundary.override_hint}`);
+  }
+  if (explanation.alternatives_considered?.length) {
+    lines.push(
+      `Alternatives: ${explanation.alternatives_considered.map((a) => `${a.type}/${a.resource}`).join(", ")}`
+    );
+  }
+  return lines;
+}
+
+module.exports = { buildExplanation, formatExplanationCard, extractFilesIntended, GATEWAY_SKILL };

package/src/lib/feedback.js

@@ -0,0 +1,65 @@
+const fs = require("fs");
+const path = require("path");
+
+const FEEDBACK_DIR = ".capint/feedback";
+
+function feedbackDir(rootDir) {
+  return path.join(rootDir, FEEDBACK_DIR);
+}
+
+function appendFeedback(rootDir, { rating, comment = "", source = "ui" } = {}) {
+  if (rating != null) {
+    const n = Number(rating);
+    if (!Number.isInteger(n) || n < 1 || n > 5) {
+      return { error: "rating must be integer 1-5" };
+    }
+  }
+  const dir = feedbackDir(rootDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const entry = {
+    ts: new Date().toISOString(),
+    rating: rating != null ? Number(rating) : null,
+    comment: String(comment || "").slice(0, 2000),
+    source: String(source || "ui")
+  };
+  const file = path.join(dir, "entries.jsonl");
+  fs.appendFileSync(file, `${JSON.stringify(entry)}\n`, "utf-8");
+  return { ok: true, entry };
+}
+
+function readEntries(rootDir) {
+  const file = path.join(feedbackDir(rootDir), "entries.jsonl");
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function summarizeFeedback(rootDir) {
+  const entries = readEntries(rootDir);
+  const rated = entries.filter((e) => typeof e.rating === "number");
+  const avg =
+    rated.length > 0 ? rated.reduce((s, e) => s + e.rating, 0) / rated.length : null;
+  const bySource = {};
+  for (const e of entries) {
+    bySource[e.source] = (bySource[e.source] || 0) + 1;
+  }
+  return {
+    count: entries.length,
+    rated_count: rated.length,
+    average_rating: avg != null ? Math.round(avg * 100) / 100 : null,
+    by_source: bySource,
+    recent: entries.slice(-5).reverse()
+  };
+}
+
+module.exports = { FEEDBACK_DIR, appendFeedback, summarizeFeedback, readEntries };

package/src/lib/i18n.js

@@ -0,0 +1,43 @@
+const fs = require("fs");
+const path = require("path");
+
+const LOCALES = new Set(["tr", "en"]);
+let cache = {};
+
+function pkgLocalesDir() {
+  return path.join(__dirname, "..", "..", "locales");
+}
+
+function loadLocale(locale) {
+  const loc = LOCALES.has(locale) ? locale : "en";
+  if (cache[loc]) return cache[loc];
+  const p = path.join(pkgLocalesDir(), `${loc}.json`);
+  if (!fs.existsSync(p)) return {};
+  cache[loc] = JSON.parse(fs.readFileSync(p, "utf-8"));
+  return cache[loc];
+}
+
+function resolveLocale(preferred) {
+  if (preferred && LOCALES.has(preferred)) return preferred;
+  const env = process.env.CAPINT_LOCALE;
+  if (env && LOCALES.has(env.trim().toLowerCase())) return env.trim().toLowerCase();
+  return "tr";
+}
+
+function parseAcceptLanguage(header) {
+  if (!header) return null;
+  const first = header.split(",")[0]?.trim().slice(0, 2).toLowerCase();
+  return LOCALES.has(first) ? first : null;
+}
+
+function t(key, locale = "tr", vars = {}) {
+  const dict = loadLocale(locale);
+  const fallback = loadLocale("en");
+  let text = dict[key] ?? fallback[key] ?? key;
+  for (const [k, v] of Object.entries(vars)) {
+    text = text.replace(new RegExp(`\\{\\{${k}\\}\\}`, "g"), String(v));
+  }
+  return text;
+}
+
+module.exports = { LOCALES, resolveLocale, parseAcceptLanguage, t, loadLocale };