@kal-elsam/kairo-runtime 0.1.0

package/src/global/global-doctor.js

@@ -0,0 +1,67 @@
+import { listBackupSnapshots } from "./backups.js";
+import { buildAdapterContext } from "./adapter-context.js";
+import { detectGlobalDrift, hasRepairableDrift } from "./drift.js";
+import { harnessHomePaths } from "./paths.js";
+import { resolveComponent } from "./component-registry.js";
+import { readGlobalState } from "./state.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoot = null } = {}) {
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+  const installedComponents = (state?.components ?? []).map((entry) => resolveComponent(entry.id, { workspaceRoot }));
+  const context = buildAdapterContext({
+    homeDir,
+    packageName: state?.packageName ?? "",
+    packageRoot,
+    workspaceRoot,
+    components: installedComponents
+  });
+  const checks = packageRoot
+    ? await detectGlobalDrift({ homeDir, paths, state, packageRoot, workspaceRoot, context })
+    : [stateOnlyCheck(state)];
+
+  if (packageRoot) {
+    checks.push(await backupsCheck(paths));
+  }
+
+  const hasMissing = checks.some((check) => check.status === "missing");
+  const hasStale = checks.some((check) => check.status === "stale");
+
+  return {
+    checks,
+    ok: !hasMissing && !hasStale,
+    hasDrift: hasRepairableDrift(checks),
+    state,
+    paths
+  };
+}
+
+function stateOnlyCheck(state) {
+  if (!state) {
+    return {
+      name: "~/.harness/state.json",
+      status: "missing",
+      category: "state",
+      detail: `Not found. Run "${formatCliCommand("install")}" to configure the local ecosystem.`
+    };
+  }
+
+  return {
+    name: "~/.harness/state.json",
+    status: "ok",
+    category: "state",
+    detail: `cliVersion=${state.cliVersion ?? "unknown"}`
+  };
+}
+
+async function backupsCheck(paths) {
+  const snapshots = await listBackupSnapshots(paths.backupsDir);
+
+  return {
+    name: "~/.harness/backups",
+    status: "ok",
+    category: "backups",
+    detail: snapshots.length > 0 ? `${snapshots.length} snapshot(s)` : "No snapshots yet."
+  };
+}

package/src/global/global-installer.js

@@ -0,0 +1,284 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { buildAdapterContext } from "./adapter-context.js";
+import { backupTimestamp } from "./backups.js";
+import { buildComponentStateEntries, resolveTargetComponents } from "./component-registry.js";
+import { installComponentAssets, repairComponentAssets } from "./component-installer.js";
+import { detectGlobalDrift, hasRepairableDrift } from "./drift.js";
+import { harnessHomePaths } from "./paths.js";
+import {
+  buildAdapterStateEntry,
+  detectInstalledAdapters,
+  resolveAdapter,
+  resolveTargetAdapters
+} from "./registry.js";
+import { createGlobalState, readGlobalState, writeGlobalState } from "./state.js";
+import {
+  getInstalledAdapterIds,
+  getInstalledComponentIds,
+  normalizeGlobalState
+} from "./state-migration.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function installGlobalHarness({
+  packageRoot,
+  packageName,
+  cliVersion,
+  homeDir,
+  workspaceRoot = null,
+  agents = null,
+  components = null,
+  noDefaultComponents = false,
+  dryRun = false
+}) {
+  const paths = harnessHomePaths(homeDir);
+  const timestamp = backupTimestamp();
+  const targetComponents = resolveTargetComponents({ components, noDefaultComponents, workspaceRoot });
+  const context = buildAdapterContext({
+    homeDir,
+    packageName,
+    packageRoot,
+    workspaceRoot,
+    components: targetComponents,
+    dryRun,
+    timestamp
+  });
+  const targetAdapters = resolveTargetAdapters(context, agents);
+  const result = {
+    scope: "agent-global",
+    homeDir,
+    stateRoot: paths.root,
+    agents: targetAdapters.map((adapter) => adapter.id),
+    components: targetComponents.map((component) => component.id),
+    coreFiles: [],
+    assetsRepaired: [],
+    assetsUnchanged: [],
+    configsCreated: [],
+    configsUpdated: [],
+    configsRepaired: [],
+    configsUnchanged: [],
+    backups: [],
+    driftDetected: false
+  };
+
+  const componentFiles = await installComponentAssets({
+    packageRoot,
+    workspaceRoot,
+    paths,
+    components: targetComponents,
+    dryRun
+  });
+  result.coreFiles.push(...Object.keys(componentFiles));
+  result.assetsRepaired.push(...Object.keys(componentFiles));
+
+  await applyAdapterPlans({ context, targetAdapters, result });
+
+  if (!dryRun) {
+    await persistGlobalState({
+      paths,
+      packageName,
+      cliVersion,
+      targetAdapters,
+      targetComponents,
+      homeDir,
+      componentFiles,
+      backups: result.backups
+    });
+  }
+
+  return result;
+}
+
+export async function updateGlobalHarness(options) {
+  const paths = harnessHomePaths(options.homeDir);
+  const state = await readGlobalState(paths.statePath);
+
+  if (!state) {
+    throw new Error(`No global state found at ~/.harness/state.json. Run "${formatCliCommand("install")}" first.`);
+  }
+
+  return syncGlobalHarness({
+    ...options,
+    agents: options.agents ?? getInstalledAdapterIds(state),
+    components: options.components ?? getInstalledComponentIds(state)
+  });
+}
+
+export async function syncGlobalHarness({
+  packageRoot,
+  packageName,
+  cliVersion,
+  homeDir,
+  workspaceRoot = null,
+  agents,
+  components,
+  dryRun = false
+}) {
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+  const timestamp = backupTimestamp();
+  const targetComponents = resolveTargetComponents({ components, workspaceRoot });
+  const context = buildAdapterContext({
+    homeDir,
+    packageName: packageName ?? state.packageName,
+    packageRoot,
+    workspaceRoot,
+    components: targetComponents,
+    dryRun,
+    timestamp
+  });
+  const targetAdapters = resolveTargetAdapters(context, agents);
+  const driftChecks = await detectGlobalDrift({ homeDir, paths, state, packageRoot, workspaceRoot, context });
+  const result = {
+    scope: "agent-global",
+    homeDir,
+    stateRoot: paths.root,
+    agents: targetAdapters.map((adapter) => adapter.id),
+    components: targetComponents.map((component) => component.id),
+    coreFiles: [],
+    assetsRepaired: [],
+    assetsUnchanged: [],
+    configsCreated: [],
+    configsUpdated: [],
+    configsRepaired: [],
+    configsUnchanged: [],
+    backups: [],
+    driftDetected: hasRepairableDrift(driftChecks),
+    repairs: driftChecks.filter((check) => check.status === "missing" || check.status === "stale")
+  };
+
+  const { coreFiles, repaired, unchanged } = await repairComponentAssets({
+    packageRoot,
+    workspaceRoot,
+    paths,
+    components: targetComponents,
+    state,
+    dryRun
+  });
+  result.coreFiles = Object.keys(coreFiles);
+  result.assetsRepaired = repaired;
+  result.assetsUnchanged = unchanged;
+
+  const driftedConfigs = new Set(
+    driftChecks
+      .filter((check) =>
+        (check.category === "managed_section" || check.category === "component_section")
+        && (check.status === "missing" || check.status === "stale")
+        && check.configFile)
+      .map((check) => check.configFile)
+  );
+
+  for (const adapter of targetAdapters) {
+    const needsRepair = driftedConfigs.has(adapter.assets.configFile);
+    if (!needsRepair) {
+      result.configsUnchanged.push(adapter.assets.configFile);
+      continue;
+    }
+
+    const plan = adapter.plan(context);
+    const applied = await adapter.apply(context, plan);
+
+    if (applied.backupPath) result.backups.push(applied.backupPath);
+    if (applied.action === "create") result.configsCreated.push(applied.configFile);
+    else if (applied.action === "update") result.configsUpdated.push(applied.configFile);
+    if (applied.action !== "unchanged") result.configsRepaired.push(applied.configFile);
+  }
+
+  if (!dryRun) {
+    await persistGlobalState({
+      paths,
+      packageName: packageName ?? state.packageName,
+      cliVersion,
+      targetAdapters,
+      targetComponents,
+      homeDir,
+      componentFiles: coreFiles,
+      backups: [...(state.backups ?? []), ...result.backups],
+      installedAt: state.installedAt
+    });
+  }
+
+  return result;
+}
+
+export async function uninstallGlobalHarness({ homeDir, dryRun = false }) {
+  const paths = harnessHomePaths(homeDir);
+  const rawState = await readGlobalState(paths.statePath);
+  const state = normalizeGlobalState(rawState);
+  const timestamp = backupTimestamp();
+  const installedComponents = state?.components?.map((entry) => entry.id) ?? [];
+  const context = buildAdapterContext({
+    homeDir,
+    packageName: state?.packageName ?? "",
+    components: installedComponents.map((id) => ({ id })),
+    dryRun,
+    timestamp
+  });
+  const adapterIds = state?.adapters?.map((entry) => entry.id)
+    ?? detectInstalledAdapters(context);
+  const result = {
+    scope: "agent-global",
+    agents: adapterIds,
+    components: installedComponents,
+    configsCleaned: [],
+    backups: [],
+    stateRemoved: false
+  };
+
+  for (const adapterId of adapterIds) {
+    const adapter = resolveAdapter(adapterId);
+    const stateEntry = state?.adapters?.find((entry) => entry.id === adapterId);
+    const removed = await adapter.uninstall(context, stateEntry);
+
+    if (removed.backupPath) result.backups.push(removed.backupPath);
+    if (removed.cleaned) result.configsCleaned.push(removed.configFile);
+  }
+
+  if (state && !dryRun) {
+    await rm(paths.statePath, { force: true });
+    await rm(join(paths.root, "components"), { recursive: true, force: true });
+    await rm(paths.coreDir, { recursive: true, force: true });
+  }
+
+  result.stateRemoved = Boolean(state);
+  return result;
+}
+
+async function applyAdapterPlans({ context, targetAdapters, result }) {
+  for (const adapter of targetAdapters) {
+    const plan = adapter.plan(context);
+    const applied = await adapter.apply(context, plan);
+
+    if (applied.backupPath) result.backups.push(applied.backupPath);
+
+    if (applied.action === "create") result.configsCreated.push(applied.configFile);
+    else if (applied.action === "update") result.configsUpdated.push(applied.configFile);
+    else if (applied.action === "unchanged") result.configsUnchanged.push(applied.configFile);
+  }
+}
+
+async function persistGlobalState({
+  paths,
+  packageName,
+  cliVersion,
+  targetAdapters,
+  targetComponents,
+  homeDir,
+  componentFiles,
+  backups,
+  installedAt
+}) {
+  const existingState = installedAt ? { installedAt } : await readGlobalState(paths.statePath);
+  const adapterEntries = targetAdapters.map((adapter) => buildAdapterStateEntry(adapter, homeDir));
+  const componentEntries = buildComponentStateEntries(targetComponents, targetAdapters);
+
+  await writeGlobalState(paths.statePath, createGlobalState({
+    packageName,
+    cliVersion,
+    adapters: adapterEntries,
+    components: componentEntries,
+    coreFiles: componentFiles,
+    backups,
+    installedAt: existingState?.installedAt
+  }));
+}

package/src/global/history.js

@@ -0,0 +1,313 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { harnessHomePaths } from "./paths.js";
+import { buildEffectivePolicy, loadConsentAudit } from "./policy.js";
+import { buildStatusReport } from "./status.js";
+
+export function getHistoryPath(homeDir) {
+  return harnessHomePaths(homeDir).historyPath;
+}
+
+export function buildCheckSnapshot(counts) {
+  if (!counts) return null;
+
+  return {
+    ok: counts.ok ?? 0,
+    missing: counts.missing ?? 0,
+    stale: counts.stale ?? 0,
+    warning: counts.warning ?? 0
+  };
+}
+
+export function createHistoryEvent({ cliVersion, ...fields }) {
+  return {
+    timestamp: new Date().toISOString(),
+    cliVersion,
+    ...fields
+  };
+}
+
+export async function appendHistoryEvent(homeDir, event) {
+  const { root, historyPath } = harnessHomePaths(homeDir);
+  await mkdir(root, { recursive: true });
+  await appendFile(historyPath, `${JSON.stringify(event)}\n`, "utf8");
+}
+
+export async function readHistoryEvents(homeDir, { limit = null, command = null, action = null } = {}) {
+  const { historyPath } = harnessHomePaths(homeDir);
+
+  if (!existsSync(historyPath)) {
+    return { events: [], warnings: [] };
+  }
+
+  const content = await readFile(historyPath, "utf8");
+  const lines = content.split("\n").filter((line) => line.trim().length > 0);
+  const events = [];
+  const warnings = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    try {
+      events.push(JSON.parse(lines[index]));
+    } catch (error) {
+      warnings.push({ line: index + 1, message: error.message });
+    }
+  }
+
+  let filtered = events;
+
+  if (command) {
+    filtered = filtered.filter((event) => event.command === command);
+  }
+
+  if (action) {
+    filtered = filtered.filter((event) => event.action === action);
+  }
+
+  if (limit != null && limit > 0) {
+    return { events: filtered.slice(-limit), warnings };
+  }
+
+  return { events: filtered, warnings };
+}
+
+export async function readLastHistoryEvent(homeDir, { command = null, action = null } = {}) {
+  const { events, warnings } = await readHistoryEvents(homeDir, { command, action });
+  return {
+    event: events.length > 0 ? events[events.length - 1] : null,
+    warnings
+  };
+}
+
+async function resolveHistoryPolicy(homeDir) {
+  const policy = await buildEffectivePolicy(homeDir);
+
+  return {
+    profile: policy.profile,
+    applyMode: policy.applyMode,
+    preflight: policy.preflight,
+    source: policy.source
+  };
+}
+
+async function resolveConsentSource(homeDir, consentOptions) {
+  const consent = await loadConsentAudit(homeDir, consentOptions);
+  return consent.consentSource;
+}
+
+function buildConsentOptions(options, { applying, dryRun }) {
+  return {
+    yes: options.yes,
+    confirm: options.confirm,
+    yesExplicit: options.yesExplicit,
+    confirmExplicit: options.confirmExplicit,
+    preflight: options.preflight,
+    preflightExplicit: options.preflightExplicit,
+    interactive: options.interactive,
+    applying,
+    dryRun,
+    json: options.json
+  };
+}
+
+async function recordEvent(homeDir, cliVersion, fields) {
+  const policy = fields.policy ?? await resolveHistoryPolicy(homeDir);
+
+  await appendHistoryEvent(homeDir, createHistoryEvent({
+    cliVersion,
+    policy,
+    consentSource: fields.consentSource ?? "none",
+    agents: fields.agents ?? null,
+    components: fields.components ?? null,
+    checksBefore: fields.checksBefore ?? null,
+    checksAfter: fields.checksAfter ?? null,
+    backupsCreated: fields.backupsCreated ?? null,
+    snapshotsUsed: fields.snapshotsUsed ?? null,
+    command: fields.command,
+    action: fields.action,
+    wrote: fields.wrote,
+    dryRun: fields.dryRun ?? false
+  }));
+}
+
+export async function recordSetupHistory(homeDir, {
+  cliVersion,
+  options,
+  outcome,
+  checksBefore = null,
+  packageRoot,
+  workspaceRoot
+}) {
+  if (options.dryRun) {
+    return;
+  }
+
+  if (outcome.cancelled) {
+    await recordEvent(homeDir, cliVersion, {
+      command: "setup",
+      action: "cancelled",
+      wrote: false,
+      dryRun: false,
+      checksBefore
+    });
+    return;
+  }
+
+  const consentSource = await resolveConsentSource(
+    homeDir,
+    buildConsentOptions(options, { applying: true, dryRun: false })
+  );
+  const postReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+
+  await recordEvent(homeDir, cliVersion, {
+    command: "setup",
+    action: "applied",
+    wrote: true,
+    dryRun: false,
+    consentSource,
+    agents: outcome.result.agents,
+    components: outcome.result.components,
+    checksBefore,
+    checksAfter: buildCheckSnapshot(postReport.counts),
+    backupsCreated: outcome.result.backups
+  });
+}
+
+export async function recordSyncHistory(homeDir, {
+  cliVersion,
+  options,
+  outcome,
+  checksBefore,
+  packageRoot,
+  workspaceRoot
+}) {
+  if (options.dryRun || outcome.action === "setup-required" || outcome.action === "noop" || outcome.action === "plan") {
+    return;
+  }
+
+  if (outcome.action === "cancelled") {
+    await recordEvent(homeDir, cliVersion, {
+      command: "sync",
+      action: "cancelled",
+      wrote: false,
+      dryRun: false,
+      checksBefore
+    });
+    return;
+  }
+
+  const consentSource = await resolveConsentSource(
+    homeDir,
+    buildConsentOptions(options, { applying: true, dryRun: false })
+  );
+  const postReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+
+  await recordEvent(homeDir, cliVersion, {
+    command: "sync",
+    action: "repaired",
+    wrote: outcome.wrote,
+    dryRun: false,
+    consentSource,
+    agents: outcome.result?.agents ?? null,
+    components: outcome.result?.components ?? null,
+    checksBefore,
+    checksAfter: buildCheckSnapshot(postReport.counts),
+    backupsCreated: outcome.result?.backups ?? null
+  });
+}
+
+export async function recordUpgradeHistory(homeDir, {
+  cliVersion,
+  options,
+  outcome,
+  checksBefore = null,
+  packageRoot,
+  workspaceRoot
+}) {
+  if (outcome.cancelled) {
+    await recordEvent(homeDir, cliVersion, {
+      command: "upgrade",
+      action: "cancelled",
+      wrote: false,
+      dryRun: false,
+      checksBefore
+    });
+    return;
+  }
+
+  if (outcome.dryRun) {
+    return;
+  }
+
+  const consentSource = await resolveConsentSource(
+    homeDir,
+    buildConsentOptions(options, { applying: true, dryRun: false })
+  );
+  const postReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+
+  await recordEvent(homeDir, cliVersion, {
+    command: "upgrade",
+    action: "applied",
+    wrote: true,
+    dryRun: false,
+    consentSource,
+    agents: outcome.result?.agents ?? null,
+    components: outcome.result?.components ?? null,
+    checksBefore,
+    checksAfter: buildCheckSnapshot(postReport.counts),
+    backupsCreated: outcome.result?.backups ?? null
+  });
+}
+
+export async function recordRollbackHistory(homeDir, {
+  cliVersion,
+  snapshot,
+  result
+}) {
+  await recordEvent(homeDir, cliVersion, {
+    command: "rollback",
+    action: result.noop ? "noop" : "applied",
+    wrote: !result.noop,
+    dryRun: false,
+    snapshotsUsed: [snapshot],
+    backupsCreated: result.safetyBackup ? [result.safetyBackup] : null
+  });
+}
+
+export async function recordUninstallHistory(homeDir, {
+  cliVersion,
+  options,
+  result
+}) {
+  if (options.dryRun) {
+    return;
+  }
+
+  await recordEvent(homeDir, cliVersion, {
+    command: "uninstall",
+    action: "applied",
+    wrote: true,
+    dryRun: false,
+    backupsCreated: result.backups
+  });
+}
+
+export async function recordPolicyHistory(homeDir, {
+  cliVersion,
+  action
+}) {
+  await recordEvent(homeDir, cliVersion, {
+    command: "policy",
+    action,
+    wrote: true,
+    dryRun: false
+  });
+}
+
+export function formatHistoryEvent(event) {
+  const wrote = event.wrote ? "yes" : "no";
+  const agents = Array.isArray(event.agents) ? event.agents.join(",") : "-";
+  const components = Array.isArray(event.components) ? event.components.join(",") : "-";
+  const consent = event.consentSource ?? "none";
+
+  return `${event.timestamp}  ${event.command.padEnd(8)} ${String(event.action).padEnd(10)} wrote=${wrote} consent=${consent} agents=${agents} components=${components}`;
+}