@kal-elsam/kairo-runtime 0.13.1 → 0.15.0

package/src/global/component-integration-cli.js

@@ -9,11 +9,13 @@ import { formatCliCommand } from "./brand/cli.js";
 import { requireIntegrationProvider } from "./integrations/provider-registry.js";
 import { ensureIntegrationProvidersRegistered } from "./integrations/index.js";
 import { ENGRAM_INTEGRATION_STATUS } from "./integrations/engram-evidence.js";
-import { SDD_HEALTH } from "./integrations/sdd-evidence.js";
+import { SDD_HEALTH, SDD_FILE_OUTCOMES } from "./integrations/sdd-evidence.js";
 import {
-  hasSuccessfulSddRollbackMutations, recordSddMaterialization, reconcileSddStateAfterRollback
+  hasSuccessfulSddRollbackMutations, recordSddMaterialization, reconcileSddStateAfterRollback,
+  adoptedHashesFromState, clearSddAdoptionsForPaths
 } from "./integrations/sdd-state.js";
 import { loadSddReceipt } from "./integrations/sdd-receipts.js";
+import { buildSddSkillResolutions } from "./integrations/sdd-resolutions.js";
 
 const DEFAULT_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -169,14 +171,24 @@ async function buildProviderContext(options, { homeDir, componentId }) {
     packageRoot: options.packageRoot ?? DEFAULT_PACKAGE_ROOT,
     persona: options.persona ?? state?.sdd?.persona ?? "off",
     personaAgentIds: state?.sdd?.personaAgentIds ?? [],
-    trackedFiles
+    trackedFiles,
+    adoptedFiles: adoptedHashesFromState(state?.sdd),
+    overwriteConflicts: Boolean(options.overwriteConflicts)
   };
 }
 
 async function persistSddReceiptState(homeDir, receipt) {
   const paths = harnessHomePaths(homeDir);
   const state = (await readGlobalState(paths.statePath)) ?? {};
-  await writeGlobalState(paths.statePath, recordSddMaterialization(state, { receipt }));
+  let next = recordSddMaterialization(state, { receipt });
+  const appliedPaths = (receipt.files ?? [])
+    .filter((file) => file.outcome === SDD_FILE_OUTCOMES.APPLIED)
+    .map((file) => file.destinationPath)
+    .filter(Boolean);
+  if (appliedPaths.length) {
+    next = clearSddAdoptionsForPaths(next, appliedPaths);
+  }
+  await writeGlobalState(paths.statePath, next);
 }
 
 async function reconcileSddRollbackState(homeDir, result) {
@@ -230,13 +242,19 @@ export function buildEngramIntegrationChecks(inspection) {
 export function buildSddIntegrationChecks(verification) {
   const summary = verification.summary ?? {};
   const persona = verification.persona ?? {};
+  const skillsHealthy = verification.status === SDD_HEALTH.CONFIGURED
+    || verification.status === SDD_HEALTH.ADOPTED;
+  const skillsCheck = {
+    name: "sdd-core:skills",
+    status: skillsHealthy ? "ok" : "warning",
+    category: "integration",
+    componentId: "sdd-core",
+    detail: `SDD skills ${verification.status}: configured=${summary.configured ?? 0}, adopted=${summary.adopted ?? 0}, missing=${summary.missing ?? 0}, drifted=${summary.drifted ?? 0}, conflict=${summary.conflict ?? 0} (disk presence ≠ runtime active).`
+  };
+  const resolutions = buildSddSkillResolutions(verification);
+  if (resolutions.length) skillsCheck.resolutions = resolutions;
   return [
-    {
-      name: "sdd-core:skills",
-      status: verification.status === SDD_HEALTH.CONFIGURED ? "ok" : "warning",
-      category: "integration", componentId: "sdd-core",
-      detail: `SDD skills ${verification.status}: configured=${summary.configured ?? 0}, missing=${summary.missing ?? 0}, drifted=${summary.drifted ?? 0}, conflict=${summary.conflict ?? 0} (disk presence ≠ runtime active).`
-    },
+    skillsCheck,
     {
       name: "sdd-core:persona",
       status: persona.status === "configured" || persona.status === "off" ? "ok" : "warning",
@@ -283,6 +301,7 @@ function printSddConfigureHuman(result) {
   if (result.dryRun) return void console.log("Dry-run only — no skills materialized.");
   if (result.cancelled) return void console.log("Cancelled.");
   if (result.blocked) return void console.log(`Blocked: ${result.reason ?? "conflicts present"}`);
+  if (result.overwriteConflicts) console.log("Mode: overwrite-conflicts (backups before replace).");
   if (result.receipt) {
     console.log(`Receipt: ${result.receipt.id}${result.receipt.partial ? " (partial)" : ""}`);
     if (result.sessionRefreshRequired) {

package/src/global/components-resolve-cli.js

@@ -0,0 +1,246 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHomeDir, harnessHomePaths } from "./paths.js";
+import { readGlobalState, writeGlobalState } from "./state.js";
+import { printJson } from "./json-output.js";
+import { formatCliCommand } from "./brand/cli.js";
+import {
+  assertExplicitApplyConsent,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "./apply-confirmation.js";
+import { ensureIntegrationProvidersRegistered } from "./integrations/index.js";
+import { requireIntegrationProvider } from "./integrations/provider-registry.js";
+import { SDD_HEALTH } from "./integrations/sdd-evidence.js";
+import {
+  adoptedHashesFromState,
+  recordSddAdoptions
+} from "./integrations/sdd-state.js";
+import { resolveCanonicalSddSkillFile } from "./integrations/sdd-destinations.js";
+import { assertComponentInstalled } from "./component-integration-cli.js";
+
+const DEFAULT_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+/** Minimal unified-style diff without external deps. */
+export function createUnifiedDiff(fromLabel, toLabel, fromText, toText) {
+  const fromLines = String(fromText ?? "").split("\n");
+  const toLines = String(toText ?? "").split("\n");
+  const lines = [`--- ${fromLabel}`, `+++ ${toLabel}`];
+  const max = Math.max(fromLines.length, toLines.length);
+  let identical = true;
+  for (let i = 0; i < max; i += 1) {
+    const a = fromLines[i];
+    const b = toLines[i];
+    if (a === b) {
+      if (a !== undefined) lines.push(` ${a}`);
+      continue;
+    }
+    identical = false;
+    if (a !== undefined) lines.push(`-${a}`);
+    if (b !== undefined) lines.push(`+${b}`);
+  }
+  if (identical) lines.push(" (no textual differences)");
+  return lines.join("\n");
+}
+
+async function buildSddContext(options) {
+  const homeDir = resolveHomeDir();
+  await assertComponentInstalled("sdd-core", { homeDir });
+  ensureIntegrationProvidersRegistered();
+  const provider = requireIntegrationProvider("sdd-core");
+  const state = await readGlobalState(harnessHomePaths(homeDir).statePath);
+  const trackedFiles = Object.fromEntries(
+    (state?.sdd?.files ?? []).map((file) => [file.destinationPath, file.hash])
+  );
+  return {
+    homeDir,
+    provider,
+    state,
+    packageRoot: options.packageRoot ?? DEFAULT_PACKAGE_ROOT,
+    requestedAgentIds: options.adapters ?? null,
+    detectedAgentIds: (state?.adapters ?? []).map((entry) => entry.id),
+    trackedFiles,
+    adoptedFiles: adoptedHashesFromState(state?.sdd),
+    personaAgentIds: state?.sdd?.personaAgentIds ?? []
+  };
+}
+
+/** Adopt conflict disk hashes into state — no file writes. */
+export async function runComponentsAdopt(options = {}) {
+  if (options.componentId !== "sdd-core") {
+    throw new Error(
+      `components adopt supports sdd-core only (got "${options.componentId}").`
+    );
+  }
+
+  const dryRun = Boolean(options.dryRun);
+  const yes = Boolean(options.yes);
+  const json = Boolean(options.json);
+  assertExplicitApplyConsent({
+    applying: !dryRun,
+    dryRun,
+    json,
+    yes,
+    interactive: null,
+    command: "components adopt sdd-core"
+  });
+
+  const ctx = await buildSddContext(options);
+  const verification = await ctx.provider.verify({
+    homeDir: ctx.homeDir,
+    packageRoot: ctx.packageRoot,
+    requestedAgentIds: ctx.requestedAgentIds,
+    detectedAgentIds: ctx.detectedAgentIds,
+    trackedFiles: ctx.trackedFiles,
+    adoptedFiles: ctx.adoptedFiles,
+    personaAgentIds: ctx.personaAgentIds
+  });
+
+  const conflicts = (verification.findings ?? []).filter(
+    (finding) => finding.status === SDD_HEALTH.CONFLICT && finding.diskHash
+  );
+  const adoptions = conflicts.map((finding) => ({
+    destinationPath: finding.destinationPath,
+    hash: finding.diskHash,
+    skillId: finding.skillId,
+    agentIds: finding.agentIds ?? [],
+    relativePath: finding.relativePath ?? "SKILL.md",
+    reason: "Adopted pre-existing disk bytes via components adopt."
+  }));
+
+  const result = {
+    provider: "sdd-core",
+    componentId: "sdd-core",
+    dryRun,
+    ok: true,
+    adopted: adoptions.length,
+    adoptions,
+    summary: verification.summary
+  };
+
+  if (dryRun) {
+    if (json) { printJson(result); return result; }
+    console.log(formatCliCommand("components adopt sdd-core"));
+    console.log(`Plan: adopt=${adoptions.length} conflict files (no writes).`);
+    for (const entry of adoptions) {
+      console.log(`  adopt    ${entry.skillId} → ${entry.destinationPath}`);
+    }
+    console.log("Dry-run only — no state updated.");
+    return result;
+  }
+
+  if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive: null })) {
+    const accepted = await promptApplyConfirmation({
+      command: "components adopt sdd-core",
+      question: `Adopt ${adoptions.length} conflicting SDD skill file(s) as-is into Kairo state? [Y/n]: `
+    });
+    if (!accepted) {
+      result.cancelled = true;
+      result.ok = false;
+      if (json) printJson(result);
+      else console.log("Cancelled.");
+      return result;
+    }
+  }
+
+  if (adoptions.length) {
+    await writeGlobalState(
+      harnessHomePaths(ctx.homeDir).statePath,
+      recordSddAdoptions(ctx.state ?? {}, { adoptions })
+    );
+  }
+
+  result.applied = true;
+  if (json) { printJson(result); return result; }
+  console.log(formatCliCommand("components adopt sdd-core"));
+  console.log(`Adopted ${adoptions.length} file(s) into Kairo state (disk unchanged).`);
+  for (const entry of adoptions) {
+    console.log(`  adopted  ${entry.skillId} → ${entry.destinationPath}`);
+  }
+  return result;
+}
+
+/** Read-only unified diff of conflict/drifted findings vs canonical. */
+export async function runComponentsDiff(options = {}) {
+  if (options.componentId !== "sdd-core") {
+    throw new Error(
+      `components diff supports sdd-core only (got "${options.componentId}").`
+    );
+  }
+
+  const ctx = await buildSddContext(options);
+  const verification = await ctx.provider.verify({
+    homeDir: ctx.homeDir,
+    packageRoot: ctx.packageRoot,
+    requestedAgentIds: ctx.requestedAgentIds,
+    detectedAgentIds: ctx.detectedAgentIds,
+    trackedFiles: ctx.trackedFiles,
+    adoptedFiles: ctx.adoptedFiles,
+    personaAgentIds: ctx.personaAgentIds
+  });
+
+  const interesting = (verification.findings ?? []).filter(
+    (finding) => finding.status === SDD_HEALTH.CONFLICT || finding.status === SDD_HEALTH.DRIFTED
+  );
+
+  const diffs = [];
+  for (const finding of interesting) {
+    let canonicalText = "";
+    let diskText = "";
+    try {
+      const canonicalPath = resolveCanonicalSddSkillFile(
+        finding.skillId,
+        finding.relativePath ?? "SKILL.md",
+        ctx.packageRoot
+      );
+      canonicalText = await readFile(canonicalPath, "utf8");
+    } catch (error) {
+      canonicalText = `/* failed to read canonical: ${error.message} */\n`;
+    }
+    try {
+      diskText = await readFile(finding.destinationPath, "utf8");
+    } catch (error) {
+      diskText = `/* failed to read disk: ${error.message} */\n`;
+    }
+    diffs.push({
+      skillId: finding.skillId,
+      status: finding.status,
+      destinationPath: finding.destinationPath,
+      agentIds: finding.agentIds ?? [],
+      unified: createUnifiedDiff(
+        `canonical/${finding.skillId}/${finding.relativePath ?? "SKILL.md"}`,
+        finding.destinationPath,
+        canonicalText,
+        diskText
+      )
+    });
+  }
+
+  const result = {
+    provider: "sdd-core",
+    componentId: "sdd-core",
+    ok: true,
+    count: diffs.length,
+    diffs,
+    summary: verification.summary
+  };
+
+  if (options.json) {
+    printJson(result);
+    return result;
+  }
+
+  console.log(formatCliCommand("components diff sdd-core"));
+  console.log(`Findings: ${diffs.length} conflict/drifted file(s).`);
+  if (diffs.length === 0) {
+    console.log("No conflicting or drifted skill files.");
+    return result;
+  }
+  for (const entry of diffs) {
+    console.log("");
+    console.log(`## ${entry.status} ${entry.skillId} (${(entry.agentIds ?? []).join(",")})`);
+    console.log(entry.unified);
+  }
+  return result;
+}

package/src/global/connection-actions.js

@@ -0,0 +1,147 @@
+/**
+ * Recommended button actions per connection chip.
+ * Optional tools never block governance; Kairo does not brew-install externals.
+ */
+import { formatCliCommand } from "./brand/cli.js";
+
+function action(id, label, command, kind = "run") {
+  return { id, label, command, kind };
+}
+
+/** @returns {{ optional: boolean, actions: Array<{id,label,command,kind}> }} */
+export function actionsForConnection(connection) {
+  if (!connection || typeof connection !== "object") {
+    return { optional: true, actions: [] };
+  }
+  const id = connection.id;
+  const state = connection.state ?? "unknown";
+
+  switch (id) {
+    case "gentle":
+      return {
+        optional: true,
+        actions: state === "available"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : [
+            action("guide-gentle", "How to install", null, "guide"),
+            action("refresh", "Refresh after install", null, "refresh")
+          ]
+      };
+    case "hermes":
+      return {
+        optional: true,
+        actions: state === "available"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : state === "unavailable" || state === "error"
+            ? [
+              action("guide-hermes-api", "Enable API tip", null, "guide"),
+              action(
+                "start-hermes",
+                "Start Hermes gateway",
+                "hermes gateway run",
+                "configure"
+              ),
+              action("refresh", "Refresh", null, "refresh")
+            ]
+            : [
+              action("guide-hermes", "How to install", null, "guide"),
+              action("refresh", "Refresh after install", null, "refresh")
+            ]
+      };
+    case "engram":
+      return {
+        optional: true,
+        actions: state === "configured"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : state === "missing"
+            ? [
+              action("guide-engram", "How to install", null, "guide"),
+              action("refresh", "Refresh after install", null, "refresh")
+            ]
+            : [
+              action(
+                "configure-engram",
+                "Configure Engram",
+                formatCliCommand("components configure engram-memory --dry-run"),
+                "configure"
+              ),
+              action("refresh", "Refresh", null, "refresh")
+            ]
+      };
+    case "graphify": {
+      const wantsUpdate = state === "stale"
+        || /graphify update/i.test(connection.detail ?? "")
+        || /No graphify-out/i.test(connection.detail ?? "");
+      const wantsInstall = state === "missing"
+        || /Install graphify/i.test(connection.detail ?? "");
+      return {
+        optional: true,
+        actions: wantsInstall
+          ? [
+            action("guide-graphify", "How to install", null, "guide"),
+            action("refresh", "Refresh after install", null, "refresh")
+          ]
+          : wantsUpdate
+            ? [
+              action("update-graph", "Update graph", "graphify update .", "configure"),
+              action("refresh", "Refresh", null, "refresh")
+            ]
+            : [action("refresh", "Refresh", null, "refresh")]
+      };
+    }
+    case "agent":
+      return {
+        optional: false,
+        actions: state === "connected"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : [
+            action("connect-agent", "Connect Agent", formatCliCommand("mcp install"), "configure"),
+            action("refresh", "Refresh", null, "refresh")
+          ]
+      };
+    default:
+      return { optional: true, actions: [] };
+  }
+}
+
+export function enrichConnection(connection) {
+  const { optional, actions } = actionsForConnection(connection);
+  return {
+    ...connection,
+    optional,
+    actions
+  };
+}
+
+/** Top-level panel buttons that are not chip-specific. */
+export function buildSetupActions({ needsAttention = false, agentConnected = false } = {}) {
+  const actions = [];
+  actions.push({
+    id: "setup",
+    label: "Setup",
+    command: formatCliCommand("setup"),
+    primary: !needsAttention && !agentConnected,
+    detail: "Detect agents you use (Cursor, Codex, Claude, …) and prepare only those."
+  });
+  if (needsAttention) {
+    actions.push({
+      id: "repair",
+      label: "Repair",
+      command: formatCliCommand("sync"),
+      primary: true
+    });
+  }
+  if (!agentConnected) {
+    actions.push({
+      id: "connect-agent",
+      label: "Connect Agent",
+      command: formatCliCommand("mcp install"),
+      primary: !needsAttention
+    });
+  }
+  actions.push(
+    { id: "doctor", label: "Doctor", command: formatCliCommand("doctor"), primary: false },
+    { id: "refresh", label: "Refresh", command: null, primary: false }
+  );
+  return actions;
+}