@kal-elsam/kairo-runtime 0.1.0

package/src/global/sync.js

@@ -0,0 +1,129 @@
+import { updateGlobalHarness } from "./global-installer.js";
+import {
+  assertExplicitApplyConsent,
+  createReadlinePrompt,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "./apply-confirmation.js";
+import { buildDiffReport } from "./diff.js";
+import { harnessHomePaths } from "./paths.js";
+import { printManagedPreflight, shouldShowPreflight, summarizeDiffPreflight } from "./preflight.js";
+import { loadConsentAudit } from "./policy.js";
+import { readGlobalState } from "./state.js";
+import { buildStatusReport } from "./status.js";
+
+export async function runHarnessSync({
+  packageRoot,
+  packageName,
+  cliVersion,
+  homeDir,
+  workspaceRoot = null,
+  dryRun = false,
+  yes = false,
+  confirm = false,
+  preflight = true,
+  preflightExplicit = false,
+  yesExplicit = false,
+  confirmExplicit = false,
+  json = false,
+  interactive = null,
+  createPrompt = createReadlinePrompt
+}) {
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+
+  if (!state) {
+    return {
+      action: "setup-required",
+      wrote: false,
+      result: null,
+      report: await buildStatusReport(homeDir, { packageRoot, workspaceRoot })
+    };
+  }
+
+  const preReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+  const needsRepair = preReport.overall === "drift"
+    || preReport.counts.missing > 0
+    || preReport.counts.stale > 0;
+
+  if (!needsRepair) {
+    return {
+      action: "noop",
+      wrote: false,
+      result: null,
+      report: preReport
+    };
+  }
+
+  const applying = !dryRun;
+
+  assertExplicitApplyConsent({
+    applying,
+    dryRun,
+    json,
+    yes,
+    confirm,
+    noPreflight: !preflight,
+    interactive,
+    command: "sync"
+  });
+
+  if (shouldShowPreflight({ preflight, dryRun, json, applying })) {
+    const diffReport = await buildDiffReport(homeDir, {
+      packageRoot,
+      packageName,
+      cliVersion,
+      workspaceRoot
+    });
+    const consent = await loadConsentAudit(homeDir, {
+      yes,
+      confirm,
+      yesExplicit,
+      confirmExplicit,
+      preflight,
+      preflightExplicit,
+      interactive,
+      applying,
+      dryRun,
+      json
+    });
+    printManagedPreflight({
+      command: "sync",
+      ...summarizeDiffPreflight(diffReport),
+      consentSource: consent.consentSource,
+      policyProfile: consent.policyProfile
+    });
+  }
+
+  if (shouldPromptApplyConfirmation({ applying, dryRun, json, confirm, interactive })) {
+    const approved = await promptApplyConfirmation({ command: "sync", createPrompt });
+    if (!approved) {
+      return {
+        action: "cancelled",
+        wrote: false,
+        result: null,
+        report: preReport
+      };
+    }
+  }
+
+  const result = await updateGlobalHarness({
+    packageRoot,
+    packageName,
+    cliVersion,
+    homeDir,
+    workspaceRoot,
+    dryRun
+  });
+
+  const report = dryRun
+    ? preReport
+    : await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+
+  return {
+    action: dryRun ? "plan" : "repaired",
+    wrote: !dryRun,
+    result,
+    report
+  };
+}

package/src/global/upgrade.js

@@ -0,0 +1,145 @@
+import { updateGlobalHarness } from "./global-installer.js";
+import {
+  assertExplicitApplyConsent,
+  createReadlinePrompt,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "./apply-confirmation.js";
+import { buildDiffReport } from "./diff.js";
+import { fetchPublishedVersion } from "./npm-registry.js";
+import { harnessHomePaths } from "./paths.js";
+import { printManagedPreflight, shouldShowPreflight, summarizeDiffPreflight } from "./preflight.js";
+import { loadConsentAudit } from "./policy.js";
+import { readGlobalState } from "./state.js";
+import { formatCliCommand } from "./brand/cli.js";
+import { runHarnessSetup } from "./setup.js";
+
+export async function runHarnessUpgrade({
+  packageRoot,
+  packageName,
+  cliVersion,
+  homeDir,
+  workspaceRoot = null,
+  dryRun = false,
+  yes = false,
+  confirm = false,
+  preflight = true,
+  preflightExplicit = false,
+  yesExplicit = false,
+  confirmExplicit = false,
+  json = false,
+  interactive = null,
+  createPrompt = createReadlinePrompt,
+  fetchVersion = fetchPublishedVersion
+}) {
+  if (yes && dryRun) {
+    throw new Error("Use either --dry-run or --yes, not both.");
+  }
+
+  const preview = !yes;
+
+  const latestVersion = await fetchVersion(packageName);
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+  const latestCommand = `npx ${packageName}@latest setup --yes`;
+  const previewCommand = `npx ${packageName}@latest setup --dry-run`;
+
+  let result = null;
+  const applying = yes && !dryRun;
+
+  assertExplicitApplyConsent({
+    applying,
+    dryRun,
+    json,
+    yes,
+    confirm,
+    noPreflight: !preflight,
+    interactive,
+    command: "upgrade"
+  });
+
+  if (yes && shouldShowPreflight({ preflight, dryRun: false, json, applying: true }) && state) {
+    const diffReport = await buildDiffReport(homeDir, {
+      packageRoot,
+      packageName,
+      cliVersion,
+      workspaceRoot
+    });
+    const consent = await loadConsentAudit(homeDir, {
+      yes,
+      confirm,
+      yesExplicit,
+      confirmExplicit,
+      preflight,
+      preflightExplicit,
+      interactive,
+      applying: true,
+      dryRun: false,
+      json
+    });
+    printManagedPreflight({
+      command: "upgrade",
+      ...summarizeDiffPreflight(diffReport),
+      consentSource: consent.consentSource,
+      policyProfile: consent.policyProfile
+    });
+  }
+
+  if (yes && shouldPromptApplyConfirmation({ applying, dryRun, json, confirm, interactive })) {
+    const approved = await promptApplyConfirmation({ command: "upgrade", createPrompt });
+    if (!approved) {
+      return {
+        cancelled: true,
+        dryRun: true,
+        wrote: false,
+        installedVersion: cliVersion,
+        latestVersion,
+        latestCommand,
+        previewCommand,
+        result: null,
+        statePresent: Boolean(state)
+      };
+    }
+  }
+
+  if (state) {
+    result = await updateGlobalHarness({
+      packageRoot,
+      packageName,
+      cliVersion,
+      homeDir,
+      workspaceRoot,
+      dryRun: preview
+    });
+  } else if (preview) {
+    const outcome = await runHarnessSetup({
+      packageRoot,
+      packageName,
+      cliVersion,
+      homeDir,
+      workspaceRoot,
+      dryRun: true,
+      yes: false,
+      interactive: false
+    });
+
+    if (outcome.cancelled) {
+      throw new Error("Upgrade preview cancelled.");
+    }
+
+    result = outcome.result;
+  } else {
+    throw new Error(`No managed state found. Run "${formatCliCommand("setup --yes")}" before upgrading.`);
+  }
+
+  return {
+    dryRun: preview,
+    wrote: !preview,
+    installedVersion: cliVersion,
+    latestVersion,
+    latestCommand,
+    previewCommand,
+    result,
+    statePresent: Boolean(state)
+  };
+}

package/src/harness-files.js

@@ -0,0 +1,145 @@
+import { constants } from "node:fs";
+import { access, readFile, readdir } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { renderTemplate } from "./text-template.js";
+
+export const MODES = new Set(["minimal", "standard", "enterprise"]);
+export const ADAPTERS = new Set(["codex", "cursor", "claude", "gemini", "copilot", "opencode", "pi"]);
+
+export const ADAPTER_PATHS = {
+  codex: [".codex/"],
+  cursor: [".cursor/"],
+  claude: [".claude/", "CLAUDE.md"],
+  gemini: ["GEMINI.md"],
+  copilot: [".github/copilot-instructions.md"],
+  opencode: [".opencode/", "opencode.json.sample"],
+  pi: [".pi/"]
+};
+
+const TEXT_EXTENSIONS = new Set([".md", ".mdc", ".json", ".yml", ".yaml", ".sample", ".sh", ".mjs"]);
+
+const MINIMAL_WHITELIST = new Set([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  "AGENT.md",
+  "docs/ai/architecture.md",
+  "docs/ai/harness.md",
+  "docs/ai/testing.md",
+  "docs/ai/git-workflow.md",
+  "docs/ai/memory.md",
+  "docs/ai/context-graph.md",
+  ".cursor/rules/core.mdc",
+  ".cursor/rules/testing.mdc",
+  ".cursor/rules/git.mdc",
+  ".github/copilot-instructions.md",
+  "setup-agent-links.sh"
+]);
+
+const STANDARD_EXCLUDED_PREFIXES = [
+  "evals/",
+  ".github/workflows/",
+  ".opencode/loops/",
+  ".gentle-ai/loops/",
+  "scripts/harness/"
+];
+
+export const COMPATIBILITY_LINKS = [
+  ["CLAUDE.md", "AGENTS.md"],
+  ["GEMINI.md", "AGENTS.md"],
+  [".claude/CLAUDE.md", "../AGENTS.md"],
+  [".agent/AGENTS.md", "../AGENTS.md"],
+  [".windsurfrules", "AGENTS.md"]
+];
+
+export async function listTemplateFiles(packageRoot, mode, options = {}) {
+  if (!MODES.has(mode)) {
+    throw new Error(`Invalid mode "${mode}". Use minimal, standard, or enterprise.`);
+  }
+
+  const templateRoot = resolve(packageRoot, "repo-template");
+  const absolutePaths = await listFilesRecursive(templateRoot);
+  const selectedAdapters = normalizeAdapters(options.adapters);
+
+  return absolutePaths
+    .map((sourcePath) => ({ sourcePath, relativePath: normalizePath(relative(templateRoot, sourcePath)) }))
+    .filter(({ relativePath }) => shouldInstall(relativePath, mode, selectedAdapters));
+}
+
+async function listFilesRecursive(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = resolve(root, entry.name);
+    if (entry.isDirectory()) files.push(...await listFilesRecursive(fullPath));
+    else if (entry.isFile()) files.push(fullPath);
+  }
+
+  return files;
+}
+
+function shouldInstall(relativePath, mode, selectedAdapters) {
+  const includedByMode = mode === "enterprise"
+    ? true
+    : mode === "minimal"
+      ? MINIMAL_WHITELIST.has(relativePath)
+      : !STANDARD_EXCLUDED_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
+
+  if (!includedByMode) return false;
+  if (!selectedAdapters) return true;
+
+  const adapter = adapterForPath(relativePath);
+  if (!adapter) return true;
+
+  return selectedAdapters.has(adapter);
+}
+
+function normalizeAdapters(adapters) {
+  if (adapters == null) return null;
+
+  const normalized = new Set();
+  for (const adapter of adapters) {
+    if (!ADAPTERS.has(adapter)) {
+      throw new Error(`Invalid adapter "${adapter}". Use ${[...ADAPTERS].join(", ")}.`);
+    }
+    normalized.add(adapter);
+  }
+  return normalized;
+}
+
+export function adapterForPath(relativePath) {
+  for (const [adapter, patterns] of Object.entries(ADAPTER_PATHS)) {
+    if (patterns.some((pattern) => relativePath === pattern || relativePath.startsWith(pattern))) {
+      return adapter;
+    }
+  }
+
+  return null;
+}
+
+export function normalizePath(filePath) {
+  return sep === "/" ? filePath : filePath.split(sep).join("/");
+}
+
+export function isTextFile(filePath) {
+  return TEXT_EXTENSIONS.has(filePath.slice(filePath.lastIndexOf(".")));
+}
+
+export async function pathExists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function renderFileContent(sourcePath, project) {
+  if (isTextFile(sourcePath)) {
+    const text = await readFile(sourcePath, "utf8");
+    return Buffer.from(renderTemplate(text, project), "utf8");
+  }
+
+  return readFile(sourcePath);
+}

package/src/harness-updater.js

@@ -0,0 +1,120 @@
+import { mkdir, readFile, symlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { COMPATIBILITY_LINKS, MODES, adapterForPath, listTemplateFiles, pathExists, renderFileContent } from "./harness-files.js";
+import { hashBuffer } from "./hash.js";
+import { createManifest, readManifest, writeManifest } from "./manifest.js";
+import { formatCliCommand } from "./global/brand/cli.js";
+
+export async function updateHarness({ project, packageRoot, packageName, cliVersion, mode, adapters, force = false, dryRun = false }) {
+  const manifest = await readManifest(project.root);
+
+  if (!manifest) {
+    throw new Error(`No .harness/manifest.json found. Run "${formatCliCommand("init")}" first.`);
+  }
+
+  const effectiveMode = mode ?? manifest.mode;
+
+  if (!MODES.has(effectiveMode)) {
+    throw new Error(`Invalid mode "${effectiveMode}". Use minimal, standard, or enterprise.`);
+  }
+
+  const effectiveAdapters = adapters == null ? manifest.adapters ?? null : [...adapters].sort();
+  const templateFiles = await listTemplateFiles(packageRoot, effectiveMode, { adapters: effectiveAdapters });
+  const result = {
+    mode: effectiveMode,
+    adapters: effectiveAdapters,
+    created: [],
+    updated: [],
+    unchanged: [],
+    skippedModified: [],
+    skippedUntracked: []
+  };
+  const nextFiles = { ...manifest.files };
+
+  for (const { relativePath, sourcePath } of templateFiles) {
+    await reconcileFile({ project, relativePath, sourcePath, manifest, force, dryRun, result, nextFiles });
+  }
+
+  await createMissingCompatibilityLinks(project.root, { adapters: effectiveAdapters, dryRun, result });
+
+  if (!dryRun) {
+    await writeManifest(project.root, createManifest({
+      packageName: manifest.packageName ?? packageName,
+      cliVersion,
+      mode: effectiveMode,
+      adapters: effectiveAdapters,
+      files: nextFiles,
+      installedAt: manifest.installedAt
+    }));
+  }
+
+  return result;
+}
+
+async function reconcileFile({ project, relativePath, sourcePath, manifest, force, dryRun, result, nextFiles }) {
+  const destinationPath = resolve(project.root, relativePath);
+  const newContent = await renderFileContent(sourcePath, project);
+  const newHash = hashBuffer(newContent);
+  const exists = await pathExists(destinationPath);
+
+  if (!exists) {
+    if (!dryRun) await writeManagedFile(destinationPath, newContent);
+    result.created.push(relativePath);
+    nextFiles[relativePath] = newHash;
+    return;
+  }
+
+  const trackedHash = manifest.files[relativePath];
+  const currentHash = hashBuffer(await readFile(destinationPath));
+  const isUnmodifiedSinceInstall = Boolean(trackedHash) && trackedHash === currentHash;
+
+  if (isUnmodifiedSinceInstall) {
+    nextFiles[relativePath] = newHash;
+
+    if (currentHash === newHash) {
+      result.unchanged.push(relativePath);
+    } else {
+      if (!dryRun) await writeManagedFile(destinationPath, newContent);
+      result.updated.push(relativePath);
+    }
+
+    return;
+  }
+
+  if (!force) {
+    result[trackedHash ? "skippedModified" : "skippedUntracked"].push(relativePath);
+    return;
+  }
+
+  if (!dryRun) await writeManagedFile(destinationPath, newContent);
+  result.updated.push(relativePath);
+  nextFiles[relativePath] = newHash;
+}
+
+async function writeManagedFile(destinationPath, content) {
+  await mkdir(dirname(destinationPath), { recursive: true });
+  await writeFile(destinationPath, content);
+}
+
+async function createMissingCompatibilityLinks(root, { adapters, dryRun, result }) {
+  for (const [linkPath, target] of COMPATIBILITY_LINKS) {
+    const adapter = adapterForPath(linkPath);
+    if (adapters && adapter && !adapters.includes(adapter)) continue;
+
+    const destination = resolve(root, linkPath);
+    const exists = await pathExists(destination);
+
+    if (exists) continue;
+
+    if (!dryRun) {
+      await mkdir(dirname(destination), { recursive: true });
+      try {
+        await symlink(target, destination);
+      } catch {
+        await writeFile(destination, `Compatibility pointer. Source of truth: ${target}\n`, "utf8");
+      }
+    }
+
+    result.created.push(linkPath);
+  }
+}

package/src/hash.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+
+export function hashBuffer(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}

package/src/manifest.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+export const MANIFEST_RELATIVE_PATH = ".harness/manifest.json";
+
+export async function readManifest(projectRoot) {
+  const manifestPath = resolve(projectRoot, MANIFEST_RELATIVE_PATH);
+  if (!existsSync(manifestPath)) return null;
+
+  try {
+    return JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeManifest(projectRoot, manifest) {
+  const manifestPath = resolve(projectRoot, MANIFEST_RELATIVE_PATH);
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+export function createManifest({ packageName, cliVersion, mode, adapters, files, installedAt }) {
+  const now = new Date().toISOString();
+
+  return {
+    packageName,
+    cliVersion,
+    mode,
+    adapters,
+    installedAt: installedAt ?? now,
+    updatedAt: now,
+    files
+  };
+}

package/src/project-detection.js

@@ -0,0 +1,105 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+
+export async function detectProject(cwd) {
+  const root = resolve(cwd);
+  const packageJsonPath = resolve(root, "package.json");
+  const packageJson = existsSync(packageJsonPath)
+    ? JSON.parse(await readFile(packageJsonPath, "utf8"))
+    : null;
+
+  const packageManager = detectPackageManager(root, packageJson);
+  const scripts = packageJson?.scripts ?? {};
+
+  return {
+    root,
+    name: packageJson?.name ?? basename(root),
+    purpose: packageJson?.description ?? "AI-assisted software project",
+    packageManager,
+    stack: detectStack(root, packageJson),
+    architecturePattern: detectArchitecture(root),
+    detectedAdapters: detectAdapters(root),
+    commands: {
+      install: installCommand(packageManager),
+      dev: scriptCommand(packageManager, scripts, "dev"),
+      lint: scriptCommand(packageManager, scripts, "lint"),
+      format: scriptCommand(packageManager, scripts, "format"),
+      typeCheck: scriptCommand(packageManager, scripts, "typecheck") ?? scriptCommand(packageManager, scripts, "type-check"),
+      test: scriptCommand(packageManager, scripts, "test"),
+      build: scriptCommand(packageManager, scripts, "build")
+    }
+  };
+}
+
+function detectPackageManager(root, packageJson) {
+  if (existsSync(resolve(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(resolve(root, "yarn.lock"))) return "yarn";
+  if (existsSync(resolve(root, "bun.lockb"))) return "bun";
+  if (existsSync(resolve(root, "package-lock.json"))) return "npm";
+
+  const declared = packageJson?.packageManager?.split("@")[0];
+  return declared ?? "npm";
+}
+
+function detectStack(root, packageJson) {
+  const dependencies = {
+    ...packageJson?.dependencies,
+    ...packageJson?.devDependencies
+  };
+
+  if (dependencies.next || existsSync(resolve(root, "next.config.js")) || existsSync(resolve(root, "next.config.mjs"))) return "Next.js";
+  if (dependencies.vite || existsSync(resolve(root, "vite.config.js")) || existsSync(resolve(root, "vite.config.ts"))) return "Vite";
+  if (dependencies.react) return "React";
+  if (existsSync(resolve(root, "pyproject.toml"))) return "Python";
+  if (existsSync(resolve(root, "go.mod"))) return "Go";
+  if (existsSync(resolve(root, "Cargo.toml"))) return "Rust";
+  if (packageJson) return "Node.js";
+  return "Unknown";
+}
+
+function detectArchitecture(root) {
+  if (existsSync(resolve(root, "src/domain")) || existsSync(resolve(root, "src/application"))) {
+    return "Layered or Clean Architecture";
+  }
+
+  if (existsSync(resolve(root, "app")) || existsSync(resolve(root, "pages"))) {
+    return "Framework-driven application";
+  }
+
+  return "To be documented";
+}
+
+function detectAdapters(root) {
+  const markers = [
+    ["codex", ".codex"],
+    ["cursor", ".cursor"],
+    ["claude", ".claude"],
+    ["claude", "CLAUDE.md"],
+    ["gemini", "GEMINI.md"],
+    ["copilot", ".github/copilot-instructions.md"],
+    ["opencode", ".opencode"],
+    ["opencode", "opencode.json"],
+    ["opencode", "opencode.json.sample"],
+    ["pi", ".pi"]
+  ];
+
+  return [...new Set(
+    markers
+      .filter(([, markerPath]) => existsSync(resolve(root, markerPath)))
+      .map(([adapter]) => adapter)
+  )].sort();
+}
+
+function installCommand(packageManager) {
+  if (packageManager === "pnpm") return "pnpm install";
+  if (packageManager === "yarn") return "yarn install";
+  if (packageManager === "bun") return "bun install";
+  return "npm install";
+}
+
+function scriptCommand(packageManager, scripts, scriptName) {
+  if (!scripts[scriptName]) return "Not configured";
+  if (packageManager === "npm") return `npm run ${scriptName}`;
+  return `${packageManager} ${scriptName}`;
+}