@bcelep/capint 0.6.5 → 0.7.0

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

@@ -1,6 +1,8 @@
 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";
 
@@ -82,7 +84,17 @@ function extractFilesIntended(text) {
   return found.slice(0, 8);
 }
 
-function buildExplanation({ text, routeResult, matrix, rootDir, matchKeywords, resolutionStatus, confirmDefaultOption }) {
+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 }
@@ -99,6 +111,15 @@ function buildExplanation({ text, routeResult, matrix, rootDir, matchKeywords, r
     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 || []
   };
@@ -123,7 +144,10 @@ function formatExplanationCard(explanation) {
   lines.push("");
   lines.push("## Explanation");
   lines.push("");
-  lines.push(`Why: ${explanation.reason_summary}`);
+  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}`);
   }

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 };

package/src/lib/providers/doctor.js

@@ -0,0 +1,205 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { loadProvidersConfig, DEFAULT_PATHS, search } = require("./local-memory-adapter");
+const { loadProvidersConfig: loadGraphCfg, DEFAULT_PATHS: GRAPH_PATHS, query } = require("./local-graph-adapter");
+const { localContextEnabled, doctorPassQuick } = require("../context-memory-bridge");
+const { resolveProviderActivation } = require("./activation-policy");
+const { loadMatrix } = require("../route-engine");
+
+const AGENTMEMORY_HEALTH_PATH = "/agentmemory/health";
+const GRAPHIFY_CANDIDATES = [
+  "GRAPH_REPORT.md",
+  "graphify-out/GRAPH_REPORT.md",
+  ".capint/graph/graph.json",
+  "graphify-out/graph.json",
+  "graph.json"
+];
+
+function fileExists(rootDir, rel) {
+  return fs.existsSync(path.join(rootDir, rel));
+}
+
+function commandExists(name) {
+  try {
+    if (process.platform === "win32") {
+      execSync(`where ${name}`, { stdio: "ignore" });
+    } else {
+      execSync(`command -v ${name}`, { stdio: "ignore" });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function probeHttpHealth(baseUrl, healthPath, timeoutMs = 2500) {
+  const url = `${String(baseUrl).replace(/\/$/, "")}${healthPath}`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    return { ok: res.ok, status: res.status, url, body };
+  } catch (e) {
+    return { ok: false, url, error: e.message };
+  }
+}
+
+function tierLocal(rootDir) {
+  const memCfg = loadProvidersConfig(rootDir);
+  const memPaths = memCfg?.memory?.paths || DEFAULT_PATHS;
+  const pathStatus = memPaths.map((p) => ({ path: p, exists: fileExists(rootDir, p) }));
+  const hits = search(rootDir, "CapInt", { config: memCfg }).hits.length;
+  const usable = pathStatus.some((p) => p.exists);
+
+  return {
+    id: "tier0_local",
+    label: "Local memory files (HANDOFF, AGENT, …)",
+    status: usable ? "ok" : "missing",
+    paths: pathStatus,
+    sample_hits: hits,
+    enable: "Always available via context-memory-bridge skill"
+  };
+}
+
+function tierGraphify(rootDir) {
+  const graphCfg = loadGraphCfg(rootDir);
+  const configured = graphCfg?.graph?.paths || GRAPH_PATHS;
+  const found = GRAPHIFY_CANDIDATES.filter((p) => fileExists(rootDir, p));
+  const configuredStatus = configured.map((p) => ({ path: p, exists: fileExists(rootDir, p) }));
+  const excerpts = query(rootDir, null, { config: graphCfg }).excerpts.length;
+  const cli = commandExists("graphify");
+
+  let status = "missing";
+  if (excerpts > 0) status = "ok";
+  else if (found.length) status = "partial";
+
+  return {
+    id: "tier1_graphify",
+    label: "Graph artifacts (graphify outputs)",
+    status,
+    artifacts_found: found,
+    configured_paths: configuredStatus,
+    sample_excerpts: excerpts,
+    cli_on_path: cli,
+    recipe: "Run graphify . then copy GRAPH_REPORT.md + graph.json — see docs/recipes/memory-graph-pairing.md"
+  };
+}
+
+async function tierAgentmemory() {
+  const baseUrl = process.env.AGENTMEMORY_URL || "http://localhost:3111";
+  const health = await probeHttpHealth(baseUrl, AGENTMEMORY_HEALTH_PATH);
+  const cli = commandExists("agentmemory");
+
+  let status = "offline";
+  if (health.ok) status = "ok";
+  else if (cli) status = "cli_only";
+
+  return {
+    id: "tier2_agentmemory",
+    label: "agentmemory MCP server",
+    status,
+    url: baseUrl,
+    health,
+    cli_on_path: cli,
+    wiring: "agentmemory connect cursor — see docs/recipes/memory-graph-pairing.md"
+  };
+}
+
+function tierMempalace() {
+  const cli = commandExists("mempalace");
+  return {
+    id: "tier3_mempalace",
+    label: "MemPalace (optional Python alt)",
+    status: cli ? "cli_only" : "not_installed",
+    cli_on_path: cli,
+    note: "Use MCP separately; CapInt adapter backlog 0.8.0. Official: github.com/MemPalace/mempalace only."
+  };
+}
+
+function envFlags() {
+  return {
+    CAPINT_LOCAL_CONTEXT: process.env.CAPINT_LOCAL_CONTEXT || null,
+    CAPINT_MEMORY: process.env.CAPINT_MEMORY || null,
+    CAPINT_GRAPH: process.env.CAPINT_GRAPH || null,
+    AGENTMEMORY_URL: process.env.AGENTMEMORY_URL || null,
+    local_context_enabled: localContextEnabled({})
+  };
+}
+
+function sampleActivation(rootDir) {
+  const matrix = loadMatrix(rootDir);
+  if (!matrix) return null;
+  return resolveProviderActivation({
+    memoryLevel: "required",
+    overallWeight: "medium",
+    capability: "memory-retrieval",
+    matrix,
+    doctorPass: doctorPassQuick(rootDir),
+    featureFlags: {}
+  });
+}
+
+function buildRecommendations(report) {
+  const rec = [];
+  if (report.tiers.tier0_local.status !== "ok") {
+    rec.push("Run capint init or add HANDOFF.md / AGENT.md for local memory.");
+  }
+  if (report.tiers.tier1_graphify.status === "missing") {
+    rec.push("Optional: run graphify . and copy GRAPH_REPORT.md + graph.json (Tier 1).");
+  }
+  if (report.tiers.tier2_agentmemory.status === "offline") {
+    rec.push("Optional: npm i -g @agentmemory/agentmemory && agentmemory (Tier 2 sidecar).");
+  }
+  if (!report.env.local_context_enabled) {
+    rec.push("Set CAPINT_LOCAL_CONTEXT=1 to attach local_adapters on route.");
+  }
+  if (report.sample_activation?.memory?.activated && report.tiers.tier2_agentmemory.status !== "ok") {
+    rec.push("Memory provider would activate on memory-retrieval routes but agentmemory is not healthy (0.7.x uses stubs until 0.8 adapter).");
+  }
+  return rec;
+}
+
+async function runProvidersDoctor(rootDir) {
+  const tiers = {
+    tier0_local: tierLocal(rootDir),
+    tier1_graphify: tierGraphify(rootDir),
+    tier2_agentmemory: await tierAgentmemory(),
+    tier3_mempalace: tierMempalace()
+  };
+
+  const providersConfig = fs.existsSync(path.join(rootDir, ".capint", "providers.json"));
+
+  const report = {
+    mode: "read_only",
+    recipe: "docs/capint-stack.md",
+    env: envFlags(),
+    providers_json: providersConfig,
+    tiers,
+    sample_activation: sampleActivation(rootDir),
+    recommendations: []
+  };
+
+  report.recommendations = buildRecommendations(report);
+  report.summary = {
+    local_ok: tiers.tier0_local.status === "ok",
+    graph_ready: tiers.tier1_graphify.status === "ok",
+    agentmemory_ok: tiers.tier2_agentmemory.status === "ok",
+    sidecar_optional: true
+  };
+
+  return report;
+}
+
+module.exports = {
+  runProvidersDoctor,
+  probeHttpHealth,
+  tierLocal,
+  tierGraphify,
+  tierAgentmemory,
+  tierMempalace
+};

package/src/lib/scaffold/index.js

@@ -1,5 +1,5 @@
 const { applyFilePolicy, buildReport } = require("./file-policy");
-const { getPresetFiles, PRESET_MANIFEST, copyBundle, normalizeBundleMode } = require("./presets");
+const { getPresetFiles, PRESET_MANIFEST, copyBundle, copyPackageSchemas, normalizeBundleMode } = require("./presets");
 const { writeScaffoldManifest } = require("./manifest");
 
 function runScaffold({
@@ -33,6 +33,7 @@ function runScaffold({
   }
 
   results.push(...copyBundle({ rootDir, force, bundle: bundleMode }));
+  results.push(...copyPackageSchemas({ rootDir, force }));
 
   const report = buildReport(results);
   report.preset = preset;

package/src/lib/scaffold/presets.js

@@ -221,6 +221,23 @@ function copyBundleTree({ rootDir, srcDir, prefix, force = false }) {
   return results;
 }
 
+function copyPackageSchemas({ rootDir, force = false }) {
+  const schemaDir = path.join(pkgRoot(), "schemas");
+  const results = [];
+  if (!fs.existsSync(schemaDir)) return results;
+  for (const file of fs.readdirSync(schemaDir).filter((f) => f.endsWith(".json"))) {
+    results.push(
+      applyFilePolicy({
+        rootDir,
+        relativePath: `.capint/schemas/${file}`,
+        content: fs.readFileSync(path.join(schemaDir, file), "utf-8"),
+        force
+      })
+    );
+  }
+  return results;
+}
+
 /** Copy skills/ + workflows/ into the target project (`full` default, `minimal` for CI). */
 function copyBundle({ rootDir, force = false, bundle = "full" }) {
   const root = pkgRoot();
@@ -262,6 +279,7 @@ const PRESET_MANIFEST = {
     description: "AGENT.md, design.md, rules, matrix, registry, skill bundle (full or --bundle minimal)",
     files: [
       "GUNLUK.md",
+      "DONE.md",
       "AGENT.md",
       "AGENTS.md",
       "design.md",
@@ -269,6 +287,7 @@ const PRESET_MANIFEST = {
       "docs/conventions/daily-use.md",
       "docs/conventions/task-to-capability-cheatsheet.md",
       ".capint/rules/core.md",
+      ".capint/schemas/",
       ".gitignore",
       "skill-routing-matrix.json",
       "registry.json",
@@ -290,6 +309,7 @@ module.exports = {
   interpolate,
   deriveRegistryFromMatrix,
   copyBundle,
+  copyPackageSchemas,
   listPackageSkillNames,
   listProjectSkillNames,
   resolveBundleSkillNames,

package/src/lib/skill-audit.js

@@ -0,0 +1,141 @@
+const fs = require("fs");
+const path = require("path");
+const { loadMatrix } = require("./route-engine");
+
+const STALE_BACKUP_DAYS = 90;
+const TIERS = ["core", "recommended", "optional", "project_added"];
+
+function loadRegistry(rootDir) {
+  const p = path.join(rootDir, "registry.json");
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch (e) {
+    return { parseError: e.message };
+  }
+}
+
+function skillsOnDisk(rootDir) {
+  const skillsDir = path.join(rootDir, "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs
+    .readdirSync(skillsDir)
+    .filter((n) => fs.existsSync(path.join(skillsDir, n, "SKILL.md")));
+}
+
+function registrySkillSet(registry) {
+  const set = new Set();
+  if (!registry || registry.parseError) return set;
+  for (const tier of TIERS) {
+    for (const name of registry[tier] || []) set.add(name);
+  }
+  return set;
+}
+
+function matrixReferencedSkills(matrix) {
+  const set = new Set();
+  for (const tt of matrix?.task_types || []) {
+    for (const s of tt.skills || []) set.add(s);
+  }
+  for (const meta of Object.values(matrix?.rules_domain_map || {})) {
+    for (const s of meta.skills || []) set.add(s);
+  }
+  return set;
+}
+
+function listStaleBackupGroups(rootDir, maxAgeDays = STALE_BACKUP_DAYS) {
+  const dir = path.join(rootDir, ".capint", "backups");
+  if (!fs.existsSync(dir)) return [];
+  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+  const stamps = new Map();
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+    const stat = fs.statSync(path.join(dir, file));
+    const m = file.match(/^(skill-routing-matrix|registry)\.(.+)\.json$/);
+    if (!m) continue;
+    const stamp = m[2];
+    const prev = stamps.get(stamp);
+    if (!prev || stat.mtimeMs > prev.mtime) {
+      stamps.set(stamp, { stamp, mtime: stat.mtimeMs });
+    }
+  }
+  return [...stamps.values()].filter((g) => g.mtime < cutoff);
+}
+
+function runSkillAudit(rootDir, options = {}) {
+  const findings = [];
+  const recommendations = [];
+  const matrix = loadMatrix(rootDir);
+  const registry = loadRegistry(rootDir);
+  const disk = skillsOnDisk(rootDir);
+  const diskSet = new Set(disk);
+  const regSet = registrySkillSet(registry);
+  const matrixRefs = matrixReferencedSkills(matrix);
+
+  for (const name of disk) {
+    if (!regSet.has(name)) {
+      findings.push({
+        level: "warning",
+        code: "orphan_on_disk",
+        skill: name,
+        message: `Skill on disk but not in registry: ${name}`
+      });
+      recommendations.push(`capint skill pin ${name}  # or remove skills/${name}/`);
+    }
+  }
+
+  if (registry && !registry.parseError) {
+    for (const name of regSet) {
+      if (!diskSet.has(name)) {
+        const level = (registry.core || []).includes(name) ? "issue" : "warning";
+        findings.push({
+          level,
+          code: "registry_ghost",
+          skill: name,
+          message: `Registry entry missing on disk: ${name}`
+        });
+        recommendations.push(`capint init --bundle full  # or remove from registry`);
+      }
+    }
+
+    for (const name of registry.optional || []) {
+      if (diskSet.has(name) && !matrixRefs.has(name)) {
+        findings.push({
+          level: "info",
+          code: "matrix_unreferenced",
+          skill: name,
+          message: `Optional skill not referenced by matrix: ${name}`
+        });
+      }
+    }
+  }
+
+  const stale = listStaleBackupGroups(rootDir, options.staleDays ?? STALE_BACKUP_DAYS);
+  for (const g of stale) {
+    findings.push({
+      level: "info",
+      code: "stale_backup",
+      stamp: g.stamp,
+      message: `Backup older than ${STALE_BACKUP_DAYS} days: ${g.stamp}`
+    });
+    recommendations.push("Review .capint/backups/ and prune old snapshots if no longer needed");
+  }
+
+  const issueCount = findings.filter((f) => f.level === "issue").length;
+  const warningCount = findings.filter((f) => f.level === "warning").length;
+
+  return {
+    pass: issueCount === 0,
+    exit_code: issueCount === 0 ? 0 : 1,
+    summary: {
+      issues: issueCount,
+      warnings: warningCount,
+      info: findings.filter((f) => f.level === "info").length,
+      skills_on_disk: disk.length,
+      registry_count: regSet.size
+    },
+    findings,
+    recommendations: [...new Set(recommendations)]
+  };
+}
+
+module.exports = { runSkillAudit, STALE_BACKUP_DAYS, skillsOnDisk, loadRegistry };