@kal-elsam/kairo-runtime 0.1.0

package/src/global/ink/run-setup-ink.js

@@ -0,0 +1,77 @@
+import React from "react";
+import { render } from "ink";
+import { WIZARD_COPY } from "../brand/index.js";
+import { loadConsentAudit } from "../policy.js";
+import { formatResultNote } from "../clack/theme.js";
+import { SetupWizardCancelledError } from "../clack/setup-wizard-constants.js";
+import { SetupApp } from "./setup-app.js";
+
+export { SetupWizardCancelledError };
+
+export async function runSetupInk({
+  homeDir,
+  workspaceRoot,
+  packageRoot,
+  packageName,
+  cliVersion,
+  dryRun = false,
+  preflight = true,
+  yes = false,
+  confirm = false,
+  preflightExplicit = false,
+  yesExplicit = false,
+  confirmExplicit = false,
+  interactive = true,
+  renderImpl = render
+}) {
+  const outcome = await new Promise((resolve) => {
+    const { waitUntilExit } = renderImpl(
+      React.createElement(SetupApp, {
+        homeDir,
+        workspaceRoot,
+        packageRoot,
+        packageName,
+        cliVersion,
+        dryRun,
+        onComplete: resolve
+      })
+    );
+
+    waitUntilExit().catch((error) => {
+      resolve({ cancelled: true, usedWizard: true, error });
+    });
+  });
+
+  if (outcome.error) {
+    throw outcome.error;
+  }
+
+  if (outcome.cancelled) {
+    return outcome;
+  }
+
+  const consent = preflight
+    ? await loadConsentAudit(homeDir, {
+      yes,
+      confirm,
+      yesExplicit,
+      confirmExplicit,
+      preflight,
+      preflightExplicit,
+      interactive,
+      applying: !dryRun,
+      dryRun,
+      json: false
+    })
+    : null;
+
+  return { ...outcome, consent };
+}
+
+export function renderSetupInkResult(result, { dryRun = false } = {}) {
+  const title = dryRun ? WIZARD_COPY.resultDryRunTitle : WIZARD_COPY.resultSuccessTitle;
+  const outro = dryRun ? WIZARD_COPY.outroDryRun : WIZARD_COPY.outroSuccess;
+  console.log(`\n${title}\n`);
+  console.log(formatResultNote(result, { dryRun }));
+  console.log(`\n${outro}\n`);
+}

package/src/global/ink/setup-app.js

@@ -0,0 +1,278 @@
+import React, { useEffect, useState } from "react";
+import { Box, Text, useApp, useInput } from "ink";
+import { stdout as output } from "node:process";
+import { BRAND, WIZARD_COPY } from "../brand/index.js";
+import { DEFAULT_COMPONENT_IDS, describeComponentCatalog } from "../component-registry.js";
+import { GLOBAL_AGENT_IDS, detectInstalledAdapters, listAdapters } from "../registry.js";
+import { buildSetupPreview, resolveComponentSelection } from "../clack/setup-preview.js";
+import {
+  SETUP_STEPS,
+  buildAgentOptions,
+  buildComponentOptions,
+  formatInkDetectPanel,
+  formatInkHeaderLines,
+  formatInkPreviewLines,
+  formatInkSelectList,
+  formatInkSplashLines,
+  INITIAL_SETUP_STEP,
+  shouldStartPreviewLoad,
+  shouldUseCompactSplashLogo,
+  toggleComponentSelection,
+  toggleSelection,
+  transitionFromSplash
+} from "./setup-state.js";
+
+const INK_COLORS = {
+  accent: "cyan",
+  success: "green",
+  warning: "yellow",
+  danger: "red",
+  muted: "gray"
+};
+
+function Header() {
+  const lines = formatInkHeaderLines();
+  return React.createElement(Box, { flexDirection: "column", marginBottom: 1 },
+    React.createElement(Text, { bold: true, color: INK_COLORS.accent }, lines[0]),
+    React.createElement(Text, { color: INK_COLORS.muted }, lines[1]),
+    React.createElement(Text, { dimColor: true }, lines[2])
+  );
+}
+
+function Panel({ title, children }) {
+  return React.createElement(Box, {
+    flexDirection: "column",
+    borderStyle: "round",
+    borderColor: INK_COLORS.accent,
+    paddingX: 1,
+    marginBottom: 1
+  },
+  React.createElement(Text, { bold: true, color: INK_COLORS.accent }, title),
+  children
+  );
+}
+
+function Footer({ children }) {
+  return React.createElement(Text, { dimColor: true }, children);
+}
+
+function Splash({ compact }) {
+  const lines = formatInkSplashLines({ compact });
+  const logoLineCount = compact ? BRAND.compactLogo.length : BRAND.asciiLogo.length;
+
+  return React.createElement(Box, { flexDirection: "column", marginBottom: 1 },
+    lines.map((line, index) => {
+      if (index < logoLineCount) {
+        return React.createElement(Text, { key: `logo-${index}`, bold: true, color: INK_COLORS.accent }, line);
+      }
+      if (line === BRAND.name) {
+        return React.createElement(Text, { key: `line-${index}`, bold: true, color: INK_COLORS.accent }, line);
+      }
+      if (line === BRAND.tagline) {
+        return React.createElement(Text, { key: `line-${index}`, color: INK_COLORS.muted }, line);
+      }
+      if (line === BRAND.splashHint) {
+        return React.createElement(Text, { key: `line-${index}`, dimColor: true }, line);
+      }
+      if (line === "") {
+        return React.createElement(Text, { key: `line-${index}` }, "");
+      }
+      return React.createElement(Text, { key: `line-${index}` }, line);
+    })
+  );
+}
+
+export function SetupApp({
+  homeDir,
+  workspaceRoot,
+  packageRoot,
+  packageName,
+  cliVersion,
+  dryRun = false,
+  onComplete
+}) {
+  const { exit } = useApp();
+  const adapters = listAdapters();
+  const detected = detectInstalledAdapters({ homeDir });
+  const componentCatalog = describeComponentCatalog({ workspaceRoot });
+  const agentOptions = buildAgentOptions(adapters, detected);
+  const componentOptions = buildComponentOptions(componentCatalog);
+  const defaultAgents = detected.length > 0 ? detected : [...GLOBAL_AGENT_IDS];
+
+  const [step, setStep] = useState(INITIAL_SETUP_STEP);
+  const useCompactSplash = shouldUseCompactSplashLogo(output.columns);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [selectedAgents, setSelectedAgents] = useState(defaultAgents);
+  const [selectedComponents, setSelectedComponents] = useState([...DEFAULT_COMPONENT_IDS]);
+  const [preview, setPreview] = useState(null);
+  const [previewError, setPreviewError] = useState(null);
+  const [previewLoading, setPreviewLoading] = useState(false);
+
+  useEffect(() => {
+    if (!shouldStartPreviewLoad({ step, preview, previewError })) return;
+
+    let cancelled = false;
+    setPreviewLoading(true);
+
+    const { noDefaults, selected } = resolveComponentSelection(selectedComponents, { workspaceRoot });
+
+    buildSetupPreview({
+      homeDir,
+      workspaceRoot,
+      packageRoot,
+      packageName,
+      cliVersion,
+      agents: selectedAgents,
+      components: selected,
+      noDefaultComponents: noDefaults
+    }).then((built) => {
+      if (cancelled) return;
+      setPreview(built);
+      setPreviewLoading(false);
+    }).catch((error) => {
+      if (cancelled) return;
+      setPreviewError(error instanceof Error ? error.message : String(error));
+      setPreviewLoading(false);
+    });
+
+    return () => {
+      cancelled = true;
+      setPreviewLoading(false);
+    };
+  }, [step, preview, previewError, homeDir, workspaceRoot, packageRoot, packageName, cliVersion, selectedAgents, selectedComponents]);
+
+  const finish = (outcome) => {
+    onComplete(outcome);
+    exit();
+  };
+
+  useInput((inputKey, key) => {
+    if (key.escape) {
+      finish({ cancelled: true, usedWizard: true });
+      return;
+    }
+
+    if (step === SETUP_STEPS.SPLASH) {
+      const splashTransition = transitionFromSplash({
+        escape: key.escape,
+        enter: key.return
+      });
+
+      if (splashTransition.kind === "cancel") {
+        finish({ cancelled: true, usedWizard: true });
+        return;
+      }
+      if (splashTransition.kind === "advance") {
+        setStep(splashTransition.step);
+      }
+      return;
+    }
+
+    if (step === SETUP_STEPS.DETECT && key.return) {
+      setStep(SETUP_STEPS.AGENTS);
+      setActiveIndex(0);
+      return;
+    }
+
+    if (step === SETUP_STEPS.AGENTS) {
+      if (key.upArrow) {
+        setActiveIndex((index) => Math.max(0, index - 1));
+        return;
+      }
+      if (key.downArrow) {
+        setActiveIndex((index) => Math.min(agentOptions.length - 1, index + 1));
+        return;
+      }
+      if (inputKey === " ") {
+        const id = agentOptions[activeIndex].id;
+        setSelectedAgents((current) => toggleSelection(current, id));
+        return;
+      }
+      if (key.return && selectedAgents.length > 0) {
+        setStep(SETUP_STEPS.COMPONENTS);
+        setActiveIndex(0);
+      }
+      return;
+    }
+
+    if (step === SETUP_STEPS.COMPONENTS) {
+      if (key.upArrow) {
+        setActiveIndex((index) => Math.max(0, index - 1));
+        return;
+      }
+      if (key.downArrow) {
+        setActiveIndex((index) => Math.min(componentOptions.length - 1, index + 1));
+        return;
+      }
+      if (inputKey === " ") {
+        const id = componentOptions[activeIndex].id;
+        setSelectedComponents((current) => toggleComponentSelection(current, id));
+        return;
+      }
+      if (key.return) {
+        setStep(SETUP_STEPS.PREVIEW);
+        setPreview(null);
+        setPreviewError(null);
+      }
+      return;
+    }
+
+    if (step === SETUP_STEPS.PREVIEW && key.return && preview && !previewLoading) {
+      setStep(SETUP_STEPS.CONFIRM);
+      return;
+    }
+
+    if (step === SETUP_STEPS.CONFIRM) {
+      if (inputKey.toLowerCase() === "y") {
+        const { noDefaults, selected } = resolveComponentSelection(selectedComponents, { workspaceRoot });
+        finish({
+          cancelled: false,
+          usedWizard: true,
+          agents: selectedAgents,
+          components: selected,
+          noDefaultComponents: noDefaults,
+          preview
+        });
+      }
+      if (inputKey.toLowerCase() === "n") {
+        finish({ cancelled: true, usedWizard: true });
+      }
+    }
+  });
+
+  const detectPanel = formatInkDetectPanel({ adapters, detected });
+
+  return React.createElement(Box, { flexDirection: "column" },
+    step === SETUP_STEPS.SPLASH && React.createElement(Splash, { compact: useCompactSplash }),
+    step !== SETUP_STEPS.SPLASH && React.createElement(Header),
+    step === SETUP_STEPS.DETECT && React.createElement(Panel, { title: WIZARD_COPY.detectTitle },
+      detectPanel.split("\n")
+        .map((line) => React.createElement(Text, { key: line }, line))
+    ),
+    step === SETUP_STEPS.AGENTS && React.createElement(Panel, { title: WIZARD_COPY.agentsPrompt },
+      formatInkSelectList({ options: agentOptions, selected: selectedAgents, activeIndex })
+        .map((line) => React.createElement(Text, { key: line }, line))
+    ),
+    step === SETUP_STEPS.COMPONENTS && React.createElement(Panel, { title: WIZARD_COPY.componentsPrompt },
+      formatInkSelectList({ options: componentOptions, selected: selectedComponents, activeIndex })
+        .map((line) => React.createElement(Text, { key: line }, line))
+    ),
+    step === SETUP_STEPS.PREVIEW && React.createElement(Panel, { title: WIZARD_COPY.previewTitle },
+      previewLoading && React.createElement(Text, { color: INK_COLORS.warning }, "Building preview…"),
+      previewError && React.createElement(Text, { color: INK_COLORS.danger }, previewError),
+      preview && formatInkPreviewLines({ preview, componentCatalog })
+        .map((line) => React.createElement(Text, { key: line }, line))
+    ),
+    step === SETUP_STEPS.CONFIRM && React.createElement(Panel, { title: "Confirm" },
+      React.createElement(Text, null, dryRun ? WIZARD_COPY.confirmDryRun : WIZARD_COPY.confirmApply)
+    ),
+    React.createElement(Footer, null,
+      step === SETUP_STEPS.SPLASH && `${BRAND.splashHint} · Esc cancel`,
+      step === SETUP_STEPS.DETECT && "Enter continue · Esc cancel",
+      step === SETUP_STEPS.AGENTS && "↑↓ move · Space toggle · Enter continue · Esc cancel",
+      step === SETUP_STEPS.COMPONENTS && "↑↓ move · Space toggle · Enter continue · Esc cancel",
+      step === SETUP_STEPS.PREVIEW && preview && !previewLoading && "Enter continue · Esc cancel",
+      step === SETUP_STEPS.CONFIRM && "Y apply · N cancel · Esc cancel"
+    )
+  );
+}

package/src/global/ink/setup-routing.js

@@ -0,0 +1,51 @@
+import { canUseSetupInk } from "./terminal.js";
+
+const BARE_SETUP_FLAGS = [
+  "interactive",
+  "dryRun",
+  "yes",
+  "confirm",
+  "json",
+  "agents",
+  "components",
+  "noDefaultComponents"
+];
+
+function isBareInteractiveSetup({
+  interactive,
+  yes = false,
+  confirm = false,
+  json = false,
+  agents = null,
+  components = null,
+  noDefaultComponents = false
+} = {}) {
+  if (!interactive || json) return false;
+  if (yes || confirm) return false;
+  if (agents != null || components != null || noDefaultComponents) return false;
+  return true;
+}
+
+export function shouldUseSetupInk({
+  interactive,
+  simple = false,
+  inkCapable = canUseSetupInk({ interactive }),
+  ...flags
+} = {}) {
+  if (simple) return false;
+  if (!isBareInteractiveSetup({ interactive, ...flags })) return false;
+  return inkCapable;
+}
+
+export function shouldUseClackWizard({
+  interactive,
+  simple = false,
+  inkCapable = canUseSetupInk({ interactive }),
+  ...flags
+} = {}) {
+  if (!isBareInteractiveSetup({ interactive, ...flags })) return false;
+  if (!simple && inkCapable) return false;
+  return true;
+}
+
+export { BARE_SETUP_FLAGS, isBareInteractiveSetup };

package/src/global/ink/setup-state.js

@@ -0,0 +1,180 @@
+import { AGENT_HINTS, BRAND, PREFERRED_CLI, formatCliCommand, getAgentLabel, WIZARD_COPY } from "../brand/index.js";
+import { formatAgentMultiselectHint } from "../clack/theme.js";
+
+export const SETUP_STEPS = {
+  SPLASH: "splash",
+  DETECT: "detect",
+  AGENTS: "agents",
+  COMPONENTS: "components",
+  PREVIEW: "preview",
+  CONFIRM: "confirm"
+};
+
+export function shouldUseCompactSplashLogo(columns) {
+  if (!columns || columns <= 0) return false;
+  const fullWidth = Math.max(...BRAND.asciiLogo.map((line) => line.length));
+  return columns < fullWidth + 4;
+}
+
+export function formatInkSplashLines({ compact = false } = {}) {
+  const logo = compact ? BRAND.compactLogo : BRAND.asciiLogo;
+  return [
+    ...logo,
+    "",
+    BRAND.name,
+    BRAND.tagline,
+    "",
+    BRAND.splashHint
+  ];
+}
+
+export const INITIAL_SETUP_STEP = SETUP_STEPS.SPLASH;
+
+export function shouldStartPreviewLoad({ step, preview, previewError }) {
+  if (step !== SETUP_STEPS.PREVIEW) return false;
+  if (preview || previewError) return false;
+  return true;
+}
+
+export function transitionFromSplash({ escape = false, enter = false } = {}) {
+  if (escape) {
+    return { kind: "cancel" };
+  }
+  if (enter) {
+    return { kind: "advance", step: SETUP_STEPS.DETECT };
+  }
+  return { kind: "noop" };
+}
+
+export function toggleSelection(selected, id) {
+  if (selected.includes(id)) {
+    return selected.filter((entry) => entry !== id);
+  }
+  return [...selected, id];
+}
+
+export function toggleComponentSelection(selected, id) {
+  if (id === "__none__") {
+    return selected.includes("__none__") ? [] : ["__none__"];
+  }
+
+  const withoutNone = selected.filter((entry) => entry !== "__none__");
+  return toggleSelection(withoutNone, id);
+}
+
+export function buildAgentOptions(adapters, detected) {
+  return adapters.map((adapter) => ({
+    id: adapter.id,
+    label: getAgentLabel(adapter.id),
+    hint: formatAgentMultiselectHint(adapter.id, detected)
+  }));
+}
+
+export function buildComponentOptions(components) {
+  return [
+    ...components.map((component) => ({
+      id: component.id,
+      label: component.label,
+      hint: component.defaultEnabled ? "recommended" : undefined
+    })),
+    {
+      id: "__none__",
+      label: WIZARD_COPY.coreOnlyLabel,
+      hint: undefined
+    }
+  ];
+}
+
+export function formatInkHeaderLines() {
+  return [
+    BRAND.name,
+    BRAND.tagline,
+    BRAND.splashLine
+  ];
+}
+
+export function formatInkDetectPanel({ adapters, detected }) {
+  const readyCount = detected.length;
+  const lines = [
+    `Your agents · ${readyCount}/${adapters.length} roots found`,
+    ""
+  ];
+
+  for (const adapter of adapters) {
+    const isReady = detected.includes(adapter.id);
+    const status = isReady ? AGENT_HINTS.ready : AGENT_HINTS.notDetected;
+    lines.push(`${getAgentLabel(adapter.id)} · ${status}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function formatInkSelectList({ options, selected, activeIndex }) {
+  return options.map((option, index) => {
+    const checked = selected.includes(option.id) ? "[x]" : "[ ]";
+    const pointer = index === activeIndex ? "›" : " ";
+    const hint = option.hint ? ` (${option.hint})` : "";
+    return `${pointer} ${checked} ${option.label}${hint}`;
+  });
+}
+
+export function formatInkPreviewLines({ preview, componentCatalog }) {
+  const labelById = new Map(componentCatalog.map((entry) => [entry.id, entry.label]));
+  const agentLine = preview.agents.map((id) => getAgentLabel(id)).join(", ") || "none";
+  const componentLine = preview.components.length > 0
+    ? preview.components.map((id) => labelById.get(id) ?? id).join(", ")
+    : WIZARD_COPY.coreOnlyLabel;
+
+  const lines = [
+    "Agents",
+    `  ${agentLine}`,
+    "",
+    "Components",
+    `  ${componentLine}`,
+    "",
+    "Managed writes"
+  ];
+
+  if (preview.preflight.changes.length === 0) {
+    lines.push("  none — already in sync");
+  } else {
+    for (const change of preview.preflight.changes) {
+      const verb = change.action === "create" ? "+" : change.action === "repair" ? "~" : "↻";
+      lines.push(`  ${verb} ${change.target}`);
+    }
+  }
+
+  lines.push("", "Preserved content");
+  if (preview.preflight.preserved.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const entry of preview.preflight.preserved) {
+      lines.push(`  ${entry.path}`);
+    }
+  }
+
+  return lines;
+}
+
+export function formatInkSuccessLines(result, { dryRun = false, cliName = PREFERRED_CLI } = {}) {
+  const agentLine = result.agents.map((id) => getAgentLabel(id)).join(", ");
+  const componentLine = result.components.length > 0
+    ? result.components.join(", ")
+    : WIZARD_COPY.coreOnlyLabel;
+
+  return [
+    dryRun ? WIZARD_COPY.resultDryRunTitle : WIZARD_COPY.resultSuccessTitle,
+    "",
+    `State   ${result.stateRoot}`,
+    `Agents  ${agentLine}`,
+    `Comps   ${componentLine}`,
+    "",
+    "Next steps",
+    dryRun
+      ? `  ${formatCliCommand("setup --confirm", cliName)}`
+      : `  ${formatCliCommand("status", cliName)}`,
+    dryRun
+      ? `  ${formatCliCommand("setup --dry-run", cliName)}`
+      : `  ${formatCliCommand("doctor", cliName)}`
+  ];
+}

package/src/global/ink/terminal.js

@@ -0,0 +1,13 @@
+import { stdin as input, stdout as output } from "node:process";
+
+export function canUseSetupInk({
+  interactive = Boolean(input.isTTY && output.isTTY),
+  term = process.env.TERM ?? "",
+  columns = output.columns ?? 80,
+  forceInk = process.env.HARNESS_INK !== "0"
+} = {}) {
+  if (!interactive || !forceInk) return false;
+  if (term === "dumb") return false;
+  if (columns > 0 && columns < 60) return false;
+  return true;
+}

package/src/global/json-output.js

@@ -0,0 +1,22 @@
+/**
+ * Stable control-plane JSON envelope for CI, tooling, and debugging.
+ * Field order and names are part of the public contract.
+ */
+export function buildControlPlaneJson(report, { cliVersion, extras = {} } = {}) {
+  return {
+    ok: report.ok,
+    overall: report.overall,
+    agents: report.agents,
+    components: report.components,
+    checks: report.checks,
+    backups: report.backups,
+    nextAction: report.nextAction,
+    policy: report.policy,
+    cliVersion,
+    ...extras
+  };
+}
+
+export function printJson(payload) {
+  console.log(JSON.stringify(payload));
+}

package/src/global/load-component-catalog.js

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { createManagedSectionBuilder } from "./component-builders.js";
+
+const defaultCatalogUrl = new URL("../../global-template/components/catalog.json", import.meta.url);
+
+function validateCatalogEntry(entry) {
+  const required = ["id", "label", "version", "defaultEnabled", "assetFiles"];
+
+  for (const field of required) {
+    if (entry[field] === undefined) {
+      throw new Error(`Component catalog entry is missing "${field}".`);
+    }
+  }
+
+  if (!Array.isArray(entry.assetFiles) || entry.assetFiles.length === 0) {
+    throw new Error(`Component "${entry.id}" must declare at least one asset file.`);
+  }
+}
+
+export function readComponentCatalogDocument(catalogUrl = defaultCatalogUrl) {
+  return JSON.parse(readFileSync(catalogUrl, "utf8"));
+}
+
+export function loadComponentCatalog(catalogUrl = defaultCatalogUrl) {
+  const catalog = readComponentCatalogDocument(catalogUrl);
+
+  return catalog.components.map((entry) => {
+    validateCatalogEntry(entry);
+
+    return {
+      id: entry.id,
+      label: entry.label,
+      version: entry.version,
+      source: "bundled",
+      defaultEnabled: entry.defaultEnabled,
+      assetFiles: [...entry.assetFiles],
+      adapterHints: { ...(entry.adapterHints ?? {}) },
+      buildManagedSection: createManagedSectionBuilder(entry.id, entry)
+    };
+  });
+}