@kal-elsam/kairo-runtime 0.1.0

package/src/global/rollback.js

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import {
+  backupFileBeforeChange,
+  backupTimestamp,
+  listBackupSnapshots,
+  resolveSnapshotDir
+} from "./backups.js";
+import { harnessHomePaths } from "./paths.js";
+
+const BLOCKED_RELATIVE_PATHS = new Set([".harness/state.json"]);
+
+export function backupNameToRelativePath(backupName) {
+  return backupName.split("__").join("/");
+}
+
+export function resolveBackupTarget(backupName, homeDir) {
+  if (!backupName || backupName.includes("..")) return null;
+
+  const relativePath = backupNameToRelativePath(backupName);
+  if (relativePath.includes("..")) return null;
+
+  const normalizedRelative = relativePath.split("/").join(sep);
+  if (BLOCKED_RELATIVE_PATHS.has(relativePath.replace(/\\/g, "/"))) return null;
+
+  const targetPath = join(homeDir, normalizedRelative);
+  const withinHome = relative(homeDir, targetPath);
+
+  if (withinHome.startsWith("..") || withinHome === "") return null;
+
+  return targetPath;
+}
+
+export function formatHomePath(homeDir, filePath) {
+  const rel = relative(homeDir, filePath);
+  return `~/${rel.split(sep).join("/")}`;
+}
+
+export async function listSnapshotFiles(snapshotDir) {
+  if (!existsSync(snapshotDir)) return [];
+
+  const entries = await readdir(snapshotDir, { withFileTypes: true });
+
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export async function describeBackupSnapshots(backupsDir) {
+  const names = await listBackupSnapshots(backupsDir);
+  const snapshots = [];
+
+  for (const name of names) {
+    const files = await listSnapshotFiles(join(backupsDir, name));
+    snapshots.push({ name, fileCount: files.length });
+  }
+
+  return snapshots;
+}
+
+function buildRestorePlans(snapshotDir, homeDir) {
+  return listSnapshotFiles(snapshotDir).then((files) =>
+    files
+      .map((backupName) => {
+        const targetPath = resolveBackupTarget(backupName, homeDir);
+        if (!targetPath) return null;
+
+        return {
+          backupName,
+          targetPath,
+          displayPath: formatHomePath(homeDir, targetPath),
+          backupPath: join(snapshotDir, backupName)
+        };
+      })
+      .filter(Boolean)
+  );
+}
+
+export async function previewRollback({ homeDir, snapshot }) {
+  const paths = harnessHomePaths(homeDir);
+  const snapshotDir = resolveSnapshotDir(paths.backupsDir, snapshot);
+  const plans = await buildRestorePlans(snapshotDir, homeDir);
+
+  return {
+    snapshot,
+    plans,
+    noop: plans.length === 0
+  };
+}
+
+export async function applyRollback({ homeDir, snapshot }) {
+  const paths = harnessHomePaths(homeDir);
+  const snapshotDir = resolveSnapshotDir(paths.backupsDir, snapshot);
+  const plans = await buildRestorePlans(snapshotDir, homeDir);
+
+  if (plans.length === 0) {
+    return { snapshot, restored: [], safetyBackup: null, noop: true };
+  }
+
+  const safetyTimestamp = backupTimestamp();
+  let safetyBackup = null;
+
+  for (const plan of plans) {
+    if (existsSync(plan.targetPath)) {
+      await backupFileBeforeChange({
+        backupsDir: paths.backupsDir,
+        homeDir,
+        filePath: plan.targetPath,
+        timestamp: safetyTimestamp
+      });
+      safetyBackup ??= safetyTimestamp;
+    }
+
+    await mkdir(dirname(plan.targetPath), { recursive: true });
+    await copyFile(plan.backupPath, plan.targetPath);
+  }
+
+  return {
+    snapshot,
+    restored: plans.map((plan) => plan.displayPath),
+    safetyBackup,
+    noop: false
+  };
+}

package/src/global/setup.js

@@ -0,0 +1,284 @@
+import { stdin as input, stdout as output } from "node:process";
+import { BRAND } from "./brand/index.js";
+import { installGlobalHarness } from "./global-installer.js";
+import {
+  assertExplicitApplyConsent,
+  createReadlinePrompt,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "./apply-confirmation.js";
+import { summarizeInstallPreflight } from "./diff.js";
+import {
+  COMPONENT_IDS,
+  DEFAULT_COMPONENT_IDS,
+  validateComponentIds
+} from "./component-registry.js";
+import {
+  GLOBAL_AGENT_IDS,
+  detectInstalledAdapters,
+  isAllAgentsSelection,
+  resolveAgentIds,
+  validateAdapterIds
+} from "./registry.js";
+import { printManagedPreflight, shouldShowPreflight } from "./preflight.js";
+import { loadConsentAudit } from "./policy.js";
+import {
+  renderSetupWizardResult,
+  runSetupWizard as defaultRunSetupWizard,
+  SetupWizardCancelledError,
+  shouldUseSetupWizard as evaluateClackWizard
+} from "./clack/setup-wizard.js";
+import {
+  renderSetupInkResult,
+  runSetupInk as defaultRunSetupInk,
+  SetupWizardCancelledError as SetupInkCancelledError
+} from "./ink/run-setup-ink.js";
+import { canUseSetupInk } from "./ink/terminal.js";
+import { shouldUseSetupInk as evaluateSetupInk } from "./ink/setup-routing.js";
+
+export { shouldUseSetupInk } from "./ink/setup-routing.js";
+export { shouldUseSetupWizard } from "./clack/setup-wizard.js";
+/** @deprecated Use shouldUseSetupWizard */
+export { shouldUseSetupTui } from "./clack/setup-wizard.js";
+
+export async function runHarnessSetup({
+  packageRoot,
+  packageName,
+  cliVersion,
+  homeDir,
+  workspaceRoot = null,
+  agents = null,
+  components = null,
+  noDefaultComponents = false,
+  dryRun = false,
+  yes = false,
+  confirm = false,
+  preflight = true,
+  preflightExplicit = false,
+  yesExplicit = false,
+  confirmExplicit = false,
+  json = false,
+  simple = false,
+  interactive = Boolean(input.isTTY && output.isTTY),
+  createPrompt = createReadlinePrompt,
+  runSetupInkImpl = defaultRunSetupInk,
+  runSetupWizardImpl = defaultRunSetupWizard,
+  inkCapable = canUseSetupInk({ interactive })
+}) {
+  const routing = { interactive, simple, inkCapable, dryRun, yes, confirm, json, agents, components, noDefaultComponents };
+  const useInk = evaluateSetupInk(routing);
+  const useWizard = !useInk && evaluateClackWizard({ ...routing, inkCapable });
+
+  let selectedAgents = agents;
+  let selectedComponents = components;
+  let selectedNoDefaults = noDefaultComponents;
+  let usedWizard = false;
+  let usedInk = false;
+
+  if (!useInk && !useWizard) {
+    printSetupIntro({ homeDir });
+  }
+
+  const setupUiArgs = {
+    homeDir,
+    workspaceRoot,
+    packageRoot,
+    packageName,
+    cliVersion,
+    dryRun,
+    preflight,
+    yes,
+    confirm,
+    preflightExplicit,
+    yesExplicit,
+    confirmExplicit,
+    interactive
+  };
+
+  if (useInk) {
+    try {
+      const inkOutcome = await runSetupInkImpl(setupUiArgs);
+
+      if (inkOutcome.cancelled) {
+        return { cancelled: true, usedWizard: true, usedInk: true };
+      }
+
+      selectedAgents = inkOutcome.agents;
+      selectedComponents = inkOutcome.components;
+      selectedNoDefaults = inkOutcome.noDefaultComponents;
+      usedWizard = true;
+      usedInk = true;
+    } catch (error) {
+      if (error instanceof SetupInkCancelledError) {
+        return { cancelled: true, usedWizard: true, usedInk: true };
+      }
+      throw error;
+    }
+  } else if (useWizard) {
+    try {
+      const wizardOutcome = await runSetupWizardImpl(setupUiArgs);
+
+      if (wizardOutcome.cancelled) {
+        return { cancelled: true, usedWizard: true };
+      }
+
+      selectedAgents = wizardOutcome.agents;
+      selectedComponents = wizardOutcome.components;
+      selectedNoDefaults = wizardOutcome.noDefaultComponents;
+      usedWizard = true;
+    } catch (error) {
+      if (error instanceof SetupWizardCancelledError) {
+        return { cancelled: true, usedWizard: true };
+      }
+      throw error;
+    }
+  } else if (
+    interactive && !dryRun && !yes && !confirm
+    && agents == null
+    && components == null
+    && !noDefaultComponents
+  ) {
+    const prompt = createPrompt();
+    const detected = detectInstalledAdapters({ homeDir });
+    const defaultAgentsLabel = detected.length > 0 ? detected.join(",") : GLOBAL_AGENT_IDS.join(",");
+
+    try {
+      const agentsAnswer = (await prompt(`Agents to configure [${defaultAgentsLabel}]: `)).trim();
+      if (agentsAnswer.length > 0) {
+        selectedAgents = parseList(agentsAnswer);
+        if (!isAllAgentsSelection(selectedAgents)) {
+          validateAdapterIds(selectedAgents);
+        }
+      }
+
+      const componentsAnswer = (await prompt(
+        `Components to install [${DEFAULT_COMPONENT_IDS.join(",")}] (or "none"): `
+      )).trim();
+
+      if (componentsAnswer.toLowerCase() === "none") {
+        selectedNoDefaults = true;
+        selectedComponents = null;
+      } else if (componentsAnswer.length > 0) {
+        selectedComponents = parseList(componentsAnswer);
+        validateComponentIds(selectedComponents, { workspaceRoot });
+      }
+
+      console.log("");
+      printSetupPlanPreview({
+        agents: resolveAgentIds(selectedAgents, { homeDir }),
+        components: selectedNoDefaults
+          ? []
+          : (selectedComponents ?? [...DEFAULT_COMPONENT_IDS])
+      });
+
+      const confirmAnswer = (await prompt("Apply this plan? [Y/n]: ")).trim().toLowerCase();
+      if (confirmAnswer === "n" || confirmAnswer === "no") {
+        console.log("Setup cancelled.");
+        return { cancelled: true };
+      }
+    } finally {
+      await prompt.close?.();
+    }
+  } else if (!useInk && !useWizard) {
+    printSetupPlanPreview({
+      agents: resolveAgentIds(selectedAgents, { homeDir }),
+      components: selectedNoDefaults
+        ? []
+        : (selectedComponents ?? [...DEFAULT_COMPONENT_IDS])
+    });
+  }
+
+  const installArgs = {
+    packageRoot,
+    packageName,
+    cliVersion,
+    homeDir,
+    workspaceRoot,
+    agents: selectedAgents,
+    components: selectedComponents,
+    noDefaultComponents: selectedNoDefaults
+  };
+
+  const applying = !dryRun;
+
+  assertExplicitApplyConsent({
+    applying,
+    dryRun,
+    json,
+    yes,
+    confirm,
+    noPreflight: !preflight,
+    interactive,
+    command: "setup"
+  });
+
+  if (!usedWizard && shouldShowPreflight({ preflight, dryRun, json, applying })) {
+    const preview = await installGlobalHarness({ ...installArgs, dryRun: true });
+    const summary = await summarizeInstallPreflight(homeDir, preview);
+    const consent = await loadConsentAudit(homeDir, {
+      yes,
+      confirm,
+      yesExplicit,
+      confirmExplicit,
+      preflight,
+      preflightExplicit,
+      interactive,
+      applying,
+      dryRun,
+      json
+    });
+    printManagedPreflight({
+      command: "setup",
+      ...summary,
+      consentSource: consent.consentSource,
+      policyProfile: consent.policyProfile
+    });
+  }
+
+  if (!usedWizard && shouldPromptApplyConfirmation({ applying, dryRun, json, confirm, interactive })) {
+    const approved = await promptApplyConfirmation({ command: "setup", createPrompt });
+    if (!approved) {
+      console.log("Setup cancelled.");
+      return { cancelled: true };
+    }
+  }
+
+  const result = await installGlobalHarness({ ...installArgs, dryRun });
+
+  if (usedInk) {
+    renderSetupInkResult(result, { dryRun });
+  } else if (usedWizard) {
+    renderSetupWizardResult(result, { dryRun });
+  }
+
+  return { cancelled: false, result, usedWizard, usedInk };
+}
+
+function printSetupIntro({ homeDir }) {
+  const detected = detectInstalledAdapters({ homeDir });
+
+  console.log(`${BRAND.displayName} setup — local AI ecosystem configurator`);
+  console.log("Configures and coordinates local agents. Does not install the AI apps themselves.");
+  console.log("");
+  console.log(`Detected agents: ${detected.join(", ") || "none"}`);
+  console.log(`Supported agents: ${GLOBAL_AGENT_IDS.join(", ")}`);
+  console.log(`Default components: ${DEFAULT_COMPONENT_IDS.join(", ")}`);
+  console.log("");
+}
+
+function printSetupPlanPreview({ agents, components }) {
+  console.log("Plan:");
+  console.log(`  Agents: ${agents.join(", ")}`);
+  console.log(`  Components: ${components.join(", ") || "none (core plumbing only)"}`);
+  console.log(`  Available components: ${COMPONENT_IDS.join(", ")}`);
+  console.log("");
+}
+
+function parseList(value) {
+  return [...new Set(
+    value
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean)
+  )];
+}

package/src/global/state-migration.js

@@ -0,0 +1,65 @@
+import { resolveAdapter } from "./registry.js";
+import { resolveComponent } from "./component-registry.js";
+
+const LEGACY_ORCHESTRATOR_COMPONENT = {
+  id: "orchestrator",
+  version: resolveComponent("orchestrator").version,
+  managedTargets: []
+};
+
+export function normalizeGlobalState(state) {
+  if (!state) return null;
+
+  const adapters = state.adapters ?? migrateLegacyAgents(state.agents ?? []);
+  const components = state.components ?? migrateLegacyComponents(state, adapters);
+
+  return {
+    ...state,
+    adapters,
+    agents: toLegacyAgents(adapters),
+    components
+  };
+}
+
+export function getInstalledAdapterIds(state) {
+  const normalized = normalizeGlobalState(state);
+  return normalized?.adapters?.map((entry) => entry.id) ?? [];
+}
+
+export function getInstalledComponentIds(state) {
+  const normalized = normalizeGlobalState(state);
+  return normalized?.components?.map((entry) => entry.id) ?? [];
+}
+
+function migrateLegacyAgents(agents) {
+  return agents.map((entry) => {
+    const adapter = resolveAdapter(entry.id);
+
+    return {
+      id: adapter.id,
+      label: adapter.label,
+      rootDir: adapter.assets.rootDir,
+      configFile: entry.configFile ?? adapter.assets.configFile,
+      managedTargets: [...adapter.assets.managedTargets],
+      present: entry.present ?? false
+    };
+  });
+}
+
+function migrateLegacyComponents(state, adapters) {
+  if (Array.isArray(state.components)) return state.components;
+
+  const managedTargets = adapters.map((adapter) => adapter.configFile);
+  const hasLegacyOrchestrator = Boolean(state.coreFiles?.["core/orchestrator.md"]);
+
+  if (!hasLegacyOrchestrator && managedTargets.length === 0) return [];
+
+  return [{
+    ...LEGACY_ORCHESTRATOR_COMPONENT,
+    managedTargets
+  }];
+}
+
+function toLegacyAgents(adapters) {
+  return adapters.map(({ id, configFile, present }) => ({ id, configFile, present }));
+}

package/src/global/state.js

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { normalizeGlobalState } from "./state-migration.js";
+
+export const STATE_VERSION = 3;
+
+export async function readGlobalState(statePath) {
+  if (!existsSync(statePath)) return null;
+
+  try {
+    const raw = JSON.parse(await readFile(statePath, "utf8"));
+    return normalizeGlobalState(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function writeGlobalState(statePath, state) {
+  await mkdir(dirname(statePath), { recursive: true });
+  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+export function createGlobalState({
+  packageName,
+  cliVersion,
+  adapters,
+  components = [],
+  coreFiles,
+  backups,
+  installedAt
+}) {
+  const now = new Date().toISOString();
+  const normalizedAdapters = adapters.map((entry) => ({ ...entry }));
+  const normalizedComponents = components.map((entry) => ({ ...entry }));
+
+  return {
+    stateVersion: STATE_VERSION,
+    packageName,
+    cliVersion,
+    scope: "agent-global",
+    installedAt: installedAt ?? now,
+    updatedAt: now,
+    adapters: normalizedAdapters,
+    agents: normalizedAdapters.map(({ id, configFile, present }) => ({ id, configFile, present })),
+    components: normalizedComponents,
+    coreFiles,
+    backups
+  };
+}

package/src/global/status.js

@@ -0,0 +1,94 @@
+import { listBackupSnapshots } from "./backups.js";
+import { runGlobalDoctorChecks } from "./global-doctor.js";
+import { buildEffectivePolicy } from "./policy.js";
+import { harnessHomePaths } from "./paths.js";
+import { GLOBAL_AGENT_IDS, detectInstalledAdapters } from "./registry.js";
+import { readGlobalState } from "./state.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function buildStatusReport(homeDir, { packageRoot, workspaceRoot = null } = {}) {
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+  const detected = detectInstalledAdapters({ homeDir });
+  const doctor = await runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoot });
+  const backups = await listBackupSnapshots(paths.backupsDir);
+
+  const installedAgentIds = new Set((state?.adapters ?? state?.agents ?? []).map((entry) => entry.id));
+  const agents = GLOBAL_AGENT_IDS.map((id) => ({
+    id,
+    detected: detected.includes(id),
+    managed: installedAgentIds.has(id)
+  }));
+
+  const components = (state?.components ?? []).map((entry) => {
+    const related = doctor.checks.filter((check) => check.componentId === entry.id);
+    const status = summarizeCheckStatuses(related);
+    return {
+      id: entry.id,
+      version: entry.version,
+      source: entry.source ?? "bundled",
+      status
+    };
+  });
+
+  const counts = {
+    ok: doctor.checks.filter((check) => check.status === "ok").length,
+    stale: doctor.checks.filter((check) => check.status === "stale").length,
+    missing: doctor.checks.filter((check) => check.status === "missing").length,
+    warning: doctor.checks.filter((check) => check.status === "warning").length
+  };
+
+  const overall = resolveOverallStatus({ state, doctor });
+  const nextAction = resolveNextAction(overall, { backups: backups.length });
+  const policy = await buildEffectivePolicy(homeDir);
+
+  return {
+    homeDir,
+    stateRoot: paths.root,
+    state,
+    agents,
+    components,
+    checks: doctor.checks,
+    backups: backups.length,
+    counts,
+    overall,
+    nextAction,
+    policy,
+    ok: overall === "ok"
+  };
+}
+
+function summarizeCheckStatuses(checks) {
+  if (checks.length === 0) return "ok";
+  if (checks.some((check) => check.status === "missing")) return "missing";
+  if (checks.some((check) => check.status === "stale")) return "stale";
+  return "ok";
+}
+
+function resolveOverallStatus({ state, doctor }) {
+  if (!state) return "missing";
+  if (doctor.hasDrift) return "drift";
+  if (!doctor.ok) return "failed";
+  return "ok";
+}
+
+function resolveNextAction(overall, { backups = 0 } = {}) {
+  switch (overall) {
+    case "missing":
+      return `Run "${formatCliCommand("setup")}" (or "${formatCliCommand("install")}") to configure the local ecosystem.`;
+    case "drift":
+      return backups > 0
+        ? `Run "${formatCliCommand("sync")}" to repair managed content. Use "${formatCliCommand("rollback")}" to restore a prior snapshot.`
+        : `Run "${formatCliCommand("sync")}" to repair managed content.`;
+    case "failed":
+      return `Run "${formatCliCommand("doctor")}" for details, then "${formatCliCommand("sync")}" or "${formatCliCommand("setup")}".`;
+    case "ok":
+      return backups > 0
+        ? `Ecosystem healthy. Use "${formatCliCommand("rollback")}" if you need a prior snapshot.`
+        : "Ecosystem healthy. No action required.";
+    default: {
+      const _exhaustive = overall;
+      return _exhaustive;
+    }
+  }
+}