@kal-elsam/kairo-runtime 0.1.0

package/src/global/adapter-context.js

@@ -0,0 +1,27 @@
+import { join } from "node:path";
+import { harnessHomePaths } from "./paths.js";
+
+export function buildAdapterContext({
+  homeDir,
+  packageName,
+  packageRoot = null,
+  workspaceRoot = null,
+  components = [],
+  dryRun = false,
+  timestamp = null
+}) {
+  const paths = harnessHomePaths(homeDir);
+
+  return {
+    homeDir,
+    paths,
+    packageRoot,
+    workspaceRoot,
+    packageName,
+    coreDir: paths.coreDir,
+    componentsDir: join(paths.root, "components"),
+    components,
+    dryRun,
+    timestamp
+  };
+}

package/src/global/adapter-matrix.js

@@ -0,0 +1,38 @@
+import { harnessHomePaths } from "./paths.js";
+import { readGlobalState } from "./state.js";
+import {
+  detectInstalledAdapters,
+  isAllAgentsSelection,
+  listAdapters
+} from "./registry.js";
+
+export async function buildAdapterMatrix(homeDir) {
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+  const detected = detectInstalledAdapters({ homeDir });
+  const installedAgentIds = new Set((state?.adapters ?? state?.agents ?? []).map((entry) => entry.id));
+
+  return listAdapters().map((adapter) => ({
+    id: adapter.id,
+    label: adapter.label,
+    rootDir: adapter.assets.rootDir,
+    configFile: adapter.assets.configFile,
+    detected: detected.includes(adapter.id),
+    managed: installedAgentIds.has(adapter.id),
+    managedTargets: [...adapter.assets.managedTargets]
+  }));
+}
+
+export async function buildAdapterMatrixReport(homeDir) {
+  const matrix = await buildAdapterMatrix(homeDir);
+  const managedCount = matrix.filter((entry) => entry.managed).length;
+  const detectedCount = matrix.filter((entry) => entry.detected).length;
+
+  return {
+    homeDir,
+    adapters: matrix,
+    managedCount,
+    detectedCount,
+    supportedCount: matrix.length
+  };
+}

package/src/global/adapters/claude.js

@@ -0,0 +1,8 @@
+import { createManagedConfigAdapter } from "../managed-config-adapter.js";
+
+export default createManagedConfigAdapter({
+  id: "claude",
+  label: "Claude Code",
+  rootDir: ".claude",
+  configFile: ".claude/CLAUDE.md"
+});

package/src/global/adapters/codex.js

@@ -0,0 +1,8 @@
+import { createManagedConfigAdapter } from "../managed-config-adapter.js";
+
+export default createManagedConfigAdapter({
+  id: "codex",
+  label: "Codex",
+  rootDir: ".codex",
+  configFile: ".codex/AGENTS.md"
+});

package/src/global/adapters/cursor.js

@@ -0,0 +1,8 @@
+import { createManagedConfigAdapter } from "../managed-config-adapter.js";
+
+export default createManagedConfigAdapter({
+  id: "cursor",
+  label: "Cursor",
+  rootDir: ".cursor",
+  configFile: ".cursor/AGENTS.md"
+});

package/src/global/adapters/opencode.js

@@ -0,0 +1,8 @@
+import { createManagedConfigAdapter } from "../managed-config-adapter.js";
+
+export default createManagedConfigAdapter({
+  id: "opencode",
+  label: "OpenCode",
+  rootDir: ".config/opencode",
+  configFile: ".config/opencode/AGENTS.md"
+});

package/src/global/agents.js

@@ -0,0 +1,7 @@
+export {
+  GLOBAL_AGENT_IDS,
+  detectInstalledAdapters as detectGlobalAgents,
+  listAdapters,
+  resolveAdapter as agentById,
+  resolveTargetAdapters
+} from "./registry.js";

package/src/global/apply-confirmation.js

@@ -0,0 +1,62 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export function isInteractiveTerminal(interactive = null) {
+  if (interactive != null) return interactive;
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+export function shouldPromptApplyConfirmation({
+  applying = true,
+  dryRun = false,
+  json = false,
+  confirm = false,
+  interactive = null
+}) {
+  if (!applying || dryRun || json || confirm) return false;
+  return isInteractiveTerminal(interactive);
+}
+
+export function assertExplicitApplyConsent({
+  applying = true,
+  dryRun = false,
+  json = false,
+  yes = false,
+  confirm = false,
+  noPreflight = false,
+  interactive = null,
+  command
+}) {
+  if (!applying || dryRun || json) return;
+  if (isInteractiveTerminal(interactive)) return;
+  if (yes || confirm || noPreflight) return;
+
+  throw new Error(
+    `Non-interactive ${command} requires --yes, --confirm, or --no-preflight before applying managed changes.`
+  );
+}
+
+export async function promptApplyConfirmation({
+  command,
+  createPrompt = createReadlinePrompt,
+  question = null
+}) {
+  const prompt = createPrompt();
+
+  try {
+    const answer = (await prompt(
+      question ?? `Apply managed changes for ${command}? [Y/n]: `
+    )).trim().toLowerCase();
+
+    return !(answer === "n" || answer === "no");
+  } finally {
+    await prompt.close?.();
+  }
+}
+
+export function createReadlinePrompt() {
+  const rl = readline.createInterface({ input, output });
+  const prompt = (question) => rl.question(question);
+  prompt.close = async () => rl.close();
+  return prompt;
+}

package/src/global/backups.js

@@ -0,0 +1,54 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { formatCliCommand } from "./brand/cli.js";
+
+export function backupTimestamp(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+
+export async function backupFileBeforeChange({ backupsDir, homeDir, filePath, timestamp, dryRun = false }) {
+  if (!existsSync(filePath)) return null;
+
+  const relativeName = relative(homeDir, filePath).split(sep).join("__");
+  const backupName = relativeName.startsWith("..") ? basename(filePath) : relativeName;
+  const backupPath = join(backupsDir, timestamp, backupName);
+
+  if (!dryRun) {
+    await mkdir(join(backupsDir, timestamp), { recursive: true });
+    await copyFile(filePath, backupPath);
+  }
+
+  return backupPath;
+}
+
+export async function listBackupSnapshots(backupsDir) {
+  if (!existsSync(backupsDir)) return [];
+
+  const entries = await readdir(backupsDir, { withFileTypes: true });
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export function assertValidSnapshotName(snapshotName) {
+  if (!snapshotName || snapshotName.includes("/") || snapshotName.includes("\\") || snapshotName.includes("..")) {
+    throw new Error(`Invalid snapshot "${snapshotName}".`);
+  }
+}
+
+export function resolveSnapshotDir(backupsDir, snapshotName) {
+  assertValidSnapshotName(snapshotName);
+
+  const snapshotDir = join(backupsDir, snapshotName);
+
+  if (!existsSync(snapshotDir)) {
+    throw new Error(
+      `Snapshot not found: "${snapshotName}". Run "${formatCliCommand("backups")}" to list available snapshots.`
+    );
+  }
+
+  return snapshotDir;
+}

package/src/global/brand/cli.js

@@ -0,0 +1,52 @@
+import { basename } from "node:path";
+
+export const PACKAGE_NAME = "@kal-elsam/kairo-runtime";
+export const LEGACY_PACKAGE_NAME = "@kal-elsam/harness";
+export const PREFERRED_CLI = "kairo";
+
+export const PREFERRED_CLI_NAMES = new Set(["kairo", "kairo-runtime"]);
+export const LEGACY_CLI_NAMES = new Set([
+  "harness",
+  "agentic-harness",
+  "sgs-harness",
+  "harness-sgs"
+]);
+export const ALL_CLI_NAMES = new Set([...PREFERRED_CLI_NAMES, ...LEGACY_CLI_NAMES]);
+
+export function isLegacyCliName(name) {
+  return LEGACY_CLI_NAMES.has(name);
+}
+
+export function legacyCliWarning(cliName) {
+  return `${cliName} is a legacy alias; prefer ${PREFERRED_CLI}`;
+}
+
+export function normalizeInvokedCliBase(argv = process.argv) {
+  const invokedBase = basename(argv[1] ?? "");
+  if (invokedBase.endsWith(".js")) {
+    return invokedBase.slice(0, -3);
+  }
+  return invokedBase;
+}
+
+export function resolveInvokedCliName(argv = process.argv) {
+  const invokedBase = normalizeInvokedCliBase(argv);
+  if (ALL_CLI_NAMES.has(invokedBase)) {
+    return invokedBase;
+  }
+  return PREFERRED_CLI;
+}
+
+export function maybeWarnLegacyCli(argv = process.argv, { json = false } = {}) {
+  if (json) return;
+
+  const invokedBase = normalizeInvokedCliBase(argv);
+  if (isLegacyCliName(invokedBase)) {
+    console.warn(`Warning: ${legacyCliWarning(invokedBase)}`);
+  }
+}
+
+export function formatCliCommand(subcommand, cliName = PREFERRED_CLI) {
+  const trimmed = subcommand.trim();
+  return trimmed ? `${cliName} ${trimmed}` : cliName;
+}

package/src/global/brand/index.js

@@ -0,0 +1,85 @@
+const KAIRO_LOGO = [
+  "██╗  ██╗ █████╗ ██╗██████╗  ██████╗ ",
+  "██║ ██╔╝██╔══██╗██║██╔══██╗██╔═══██╗",
+  "█████╔╝ ███████║██║██████╔╝██║   ██║",
+  "██╔═██╗ ██╔══██║██║██╔══██╗██║   ██║",
+  "██║  ██╗██║  ██║██║██║  ██║╚██████╔╝",
+  "╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝ ╚═════╝ "
+];
+
+const COMPACT_LOGO = [
+  " _  __ ___ _ __  ",
+  "| |/ /|_ _| '_ \\ ",
+  "| ' <  | || |_) |",
+  "|_|\\_\\|___| .__/ ",
+  "          |_|    "
+];
+
+export const BRAND = {
+  name: "KAIRO RUNTIME",
+  displayName: "Kairo Runtime",
+  tagline: "Local Agent Operating System",
+  splashLine: "Coordinates local AI agents — does not install the apps themselves.",
+  asciiLogo: KAIRO_LOGO,
+  compactLogo: COMPACT_LOGO,
+  splashHint: "Press Enter to continue",
+  wizardCancelMessage: "Setup cancelled."
+};
+
+export const AGENT_LABELS = {
+  cursor: "Cursor",
+  codex: "Codex",
+  opencode: "OpenCode",
+  claude: "Claude Code"
+};
+
+export const AGENT_SYMBOLS = {
+  cursor: "◆",
+  codex: "◆",
+  opencode: "◆",
+  claude: "◆"
+};
+
+export const TOKENS = {
+  success: "green",
+  warning: "yellow",
+  danger: "red",
+  muted: "gray",
+  accent: "cyan"
+};
+
+export const AGENT_HINTS = {
+  ready: "ready",
+  notDetected: "not detected",
+  managedLater: "managed later"
+};
+
+export const WIZARD_COPY = {
+  introTitle: `${BRAND.displayName} — ${BRAND.tagline}`,
+  splashTitle: "Welcome",
+  detectTitle: "Your agents",
+  agentsPrompt: `Which agents should ${BRAND.displayName} manage?`,
+  componentsPrompt: "Which components should be installed?",
+  previewTitle: "Plan preview",
+  confirmDryRun: "Preview only — no files will be written. Continue?",
+  confirmApply: "Apply this plan? Backups run before config writes when needed.",
+  resultDryRunTitle: "Dry run complete",
+  resultSuccessTitle: "Setup complete",
+  outroDryRun: "Nothing was written.",
+  outroSuccess: "Your local agent OS is ready.",
+  coreOnlyLabel: "Core only (no components)"
+};
+
+export function getAgentLabel(agentId) {
+  return AGENT_LABELS[agentId] ?? agentId;
+}
+
+export function getAgentSymbol(agentId) {
+  return AGENT_SYMBOLS[agentId] ?? "•";
+}
+
+export function commandHeader(label) {
+  return `${BRAND.displayName} ${label}`;
+}
+
+export { formatCliCommand, PREFERRED_CLI } from "./cli.js";

package/src/global/clack/setup-preview.js

@@ -0,0 +1,48 @@
+import { installGlobalHarness } from "../global-installer.js";
+import { summarizeInstallPreflight } from "../diff.js";
+import {
+  DEFAULT_COMPONENT_IDS,
+  validateComponentIds
+} from "../component-registry.js";
+import { validateAdapterIds } from "../registry.js";
+
+export async function buildSetupPreview({
+  homeDir,
+  workspaceRoot,
+  packageRoot,
+  packageName,
+  cliVersion,
+  agents,
+  components,
+  noDefaultComponents
+}) {
+  const validatedAgents = validateAdapterIds(agents);
+  const plan = await installGlobalHarness({
+    packageRoot,
+    packageName,
+    cliVersion,
+    homeDir,
+    workspaceRoot,
+    agents: validatedAgents,
+    components,
+    noDefaultComponents,
+    dryRun: true
+  });
+  const preflight = await summarizeInstallPreflight(homeDir, plan);
+
+  return {
+    agents: validatedAgents,
+    components: noDefaultComponents ? [] : (components ?? [...DEFAULT_COMPONENT_IDS]),
+    plan,
+    preflight
+  };
+}
+
+export function resolveComponentSelection(selectedIds, { workspaceRoot }) {
+  if (selectedIds.includes("__none__")) {
+    return { noDefaults: true, selected: [] };
+  }
+
+  const selected = validateComponentIds(selectedIds, { workspaceRoot });
+  return { noDefaults: false, selected };
+}

package/src/global/clack/setup-wizard-constants.js

@@ -0,0 +1,6 @@
+export class SetupWizardCancelledError extends Error {
+  constructor() {
+    super("Setup cancelled.");
+    this.name = "SetupWizardCancelledError";
+  }
+}

package/src/global/clack/setup-wizard.js

@@ -0,0 +1,207 @@
+import * as defaultPrompts from "@clack/prompts";
+import { BRAND, getAgentLabel, WIZARD_COPY } from "../brand/index.js";
+import { canUseSetupInk } from "../ink/terminal.js";
+import { shouldUseClackWizard } from "../ink/setup-routing.js";
+import { describeComponentCatalog, DEFAULT_COMPONENT_IDS } from "../component-registry.js";
+import { loadConsentAudit } from "../policy.js";
+import {
+  GLOBAL_AGENT_IDS,
+  detectInstalledAdapters,
+  listAdapters,
+  validateAdapterIds
+} from "../registry.js";
+import {
+  buildSetupPreview,
+  resolveComponentSelection
+} from "./setup-preview.js";
+import { SetupWizardCancelledError } from "./setup-wizard-constants.js";
+import {
+  brandIntroTitle,
+  formatAgentDetectCard,
+  formatAgentMultiselectHint,
+  formatComponentMultiselectHint,
+  formatPreviewNote,
+  formatResultNote,
+  formatSplashNote
+} from "./theme.js";
+
+export { SetupWizardCancelledError };
+
+export function shouldUseSetupWizard({
+  interactive,
+  simple = false,
+  inkCapable = canUseSetupInk({ interactive }),
+  dryRun = false,
+  yes = false,
+  confirm = false,
+  json = false,
+  agents = null,
+  components = null,
+  noDefaultComponents = false
+} = {}) {
+  return shouldUseClackWizard({
+    interactive,
+    simple,
+    inkCapable,
+    dryRun,
+    yes,
+    confirm,
+    json,
+    agents,
+    components,
+    noDefaultComponents
+  });
+}
+
+/** @deprecated Use shouldUseSetupWizard */
+export const shouldUseSetupTui = shouldUseSetupWizard;
+
+function handleCancel(prompts, message = BRAND.wizardCancelMessage) {
+  prompts.cancel(message);
+  return { cancelled: true, usedWizard: true };
+}
+
+export async function runSetupWizard({
+  homeDir,
+  workspaceRoot,
+  packageRoot,
+  packageName,
+  cliVersion,
+  dryRun = false,
+  preflight = true,
+  yes = false,
+  confirm = false,
+  preflightExplicit = false,
+  yesExplicit = false,
+  confirmExplicit = false,
+  interactive = true,
+  prompts = defaultPrompts
+}) {
+  const detected = detectInstalledAdapters({ homeDir });
+  const adapters = listAdapters();
+  const components = describeComponentCatalog({ workspaceRoot });
+  const defaultAgents = detected.length > 0 ? detected : [...GLOBAL_AGENT_IDS];
+
+  try {
+    prompts.intro(brandIntroTitle());
+    prompts.note(formatSplashNote(), WIZARD_COPY.splashTitle);
+
+    prompts.note(
+      formatAgentDetectCard({ adapters, detected }),
+      WIZARD_COPY.detectTitle
+    );
+
+    const agentSelection = await prompts.multiselect({
+      message: WIZARD_COPY.agentsPrompt,
+      options: adapters.map((adapter) => ({
+        value: adapter.id,
+        label: getAgentLabel(adapter.id),
+        hint: formatAgentMultiselectHint(adapter.id, detected)
+      })),
+      initialValues: defaultAgents,
+      required: true
+    });
+
+    if (prompts.isCancel(agentSelection)) {
+      return handleCancel(prompts);
+    }
+
+    const agents = validateAdapterIds(agentSelection);
+    const defaultComponents = [...DEFAULT_COMPONENT_IDS];
+    const componentSelection = await prompts.multiselect({
+      message: WIZARD_COPY.componentsPrompt,
+      options: [
+        ...components.map((component) => ({
+          value: component.id,
+          label: component.label,
+          hint: formatComponentMultiselectHint(component)
+        })),
+        {
+          value: "__none__",
+          label: WIZARD_COPY.coreOnlyLabel
+        }
+      ],
+      initialValues: defaultComponents,
+      required: false
+    });
+
+    if (prompts.isCancel(componentSelection)) {
+      return handleCancel(prompts);
+    }
+
+    const { noDefaults: noDefaultComponents, selected: selectedComponents } = resolveComponentSelection(
+      componentSelection,
+      { workspaceRoot }
+    );
+
+    const preview = await buildSetupPreview({
+      homeDir,
+      workspaceRoot,
+      packageRoot,
+      packageName,
+      cliVersion,
+      agents,
+      components: selectedComponents,
+      noDefaultComponents
+    });
+
+    prompts.note(
+      formatPreviewNote({ preview, componentCatalog: components }),
+      WIZARD_COPY.previewTitle
+    );
+
+    const approved = await prompts.confirm({
+      message: dryRun ? WIZARD_COPY.confirmDryRun : WIZARD_COPY.confirmApply,
+      initialValue: true
+    });
+
+    if (prompts.isCancel(approved) || !approved) {
+      return handleCancel(prompts);
+    }
+
+    const consent = preflight
+      ? await loadConsentAudit(homeDir, {
+        yes,
+        confirm,
+        yesExplicit,
+        confirmExplicit,
+        preflight,
+        preflightExplicit,
+        interactive,
+        applying: !dryRun,
+        dryRun,
+        json: false
+      })
+      : null;
+
+    return {
+      cancelled: false,
+      usedWizard: true,
+      agents,
+      components: selectedComponents,
+      noDefaultComponents,
+      preview,
+      consent
+    };
+  } catch (error) {
+    if (error instanceof SetupWizardCancelledError) {
+      return handleCancel(prompts);
+    }
+    prompts.log.error(error instanceof Error ? error.message : String(error));
+    throw error;
+  }
+}
+
+/** @deprecated Use runSetupWizard */
+export const runSetupTui = runSetupWizard;
+
+export function renderSetupWizardResult(result, { dryRun = false, prompts = defaultPrompts } = {}) {
+  prompts.note(
+    formatResultNote(result, { dryRun }),
+    dryRun ? WIZARD_COPY.resultDryRunTitle : WIZARD_COPY.resultSuccessTitle
+  );
+  prompts.outro(dryRun ? WIZARD_COPY.outroDryRun : WIZARD_COPY.outroSuccess);
+}
+
+/** @deprecated Use renderSetupWizardResult */
+export const renderSetupTuiResult = renderSetupWizardResult;