@kal-elsam/kairo-runtime 0.1.0

package/src/global/component-registry.js

@@ -0,0 +1,89 @@
+import { loadComponentCatalog } from "./load-component-catalog.js";
+import { loadWorkspaceComponentCatalog } from "./load-workspace-component-catalog.js";
+
+const BUNDLED_COMPONENTS = loadComponentCatalog();
+
+export const DEFAULT_COMPONENT_IDS = BUNDLED_COMPONENTS
+  .filter((component) => component.defaultEnabled)
+  .map((component) => component.id);
+
+export const COMPONENT_IDS = BUNDLED_COMPONENTS.map((component) => component.id);
+
+function loadWorkspaceComponents(workspaceRoot) {
+  if (!workspaceRoot) return [];
+
+  return loadWorkspaceComponentCatalog(workspaceRoot, { bundledIds: COMPONENT_IDS });
+}
+
+function mergeComponents(workspaceRoot) {
+  return [...BUNDLED_COMPONENTS, ...loadWorkspaceComponents(workspaceRoot)];
+}
+
+function formatCatalogEntry(component) {
+  return {
+    id: component.id,
+    label: component.label,
+    version: component.version,
+    source: component.source ?? "bundled",
+    defaultEnabled: component.defaultEnabled,
+    assetFiles: [...component.assetFiles],
+    adapterHints: Object.keys(component.adapterHints),
+    instructions: component.instructions ?? null
+  };
+}
+
+export function listComponents({ workspaceRoot = null } = {}) {
+  return mergeComponents(workspaceRoot);
+}
+
+export function describeComponentCatalog({ workspaceRoot = null } = {}) {
+  return listComponents({ workspaceRoot }).map(formatCatalogEntry);
+}
+
+export function describeBundledComponentCatalog() {
+  return BUNDLED_COMPONENTS.map(formatCatalogEntry);
+}
+
+export function describeWorkspaceComponentCatalog(workspaceRoot) {
+  return loadWorkspaceComponents(workspaceRoot).map(formatCatalogEntry);
+}
+
+export function resolveComponent(id, { workspaceRoot = null } = {}) {
+  const component = mergeComponents(workspaceRoot).find((candidate) => candidate.id === id);
+
+  if (!component) {
+    const available = mergeComponents(workspaceRoot).map((entry) => entry.id);
+    throw new Error(`Unknown component "${id}". Use ${available.join(", ")}.`);
+  }
+
+  return component;
+}
+
+export function validateComponentIds(ids, { workspaceRoot = null } = {}) {
+  return ids.map((id) => resolveComponent(id, { workspaceRoot }).id);
+}
+
+export function resolveTargetComponents({
+  components = null,
+  noDefaultComponents = false,
+  workspaceRoot = null
+} = {}) {
+  if (components != null) {
+    return validateComponentIds(components, { workspaceRoot }).map((id) => resolveComponent(id, { workspaceRoot }));
+  }
+
+  if (noDefaultComponents) return [];
+
+  return DEFAULT_COMPONENT_IDS.map((id) => resolveComponent(id, { workspaceRoot }));
+}
+
+export function buildComponentStateEntries(components, adapters) {
+  const managedTargets = adapters.map((adapter) => adapter.assets.configFile);
+
+  return components.map((component) => ({
+    id: component.id,
+    version: component.version,
+    source: component.source ?? "bundled",
+    managedTargets: [...managedTargets]
+  }));
+}

package/src/global/components/orchestrator.js

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+
+export function buildOrchestratorManagedSection(context, adapter) {
+  const contractPath = join(context.componentsDir, "orchestrator", "orchestrator.md");
+
+  return [
+    "### Orchestrator",
+    "",
+    `- Contract: ${contractPath}`,
+    "- Coordinates cross-agent handoffs; does not replace any agent.",
+    `- Adapter target: ~/${adapter.assets.configFile}`,
+    "- Repository AGENTS.md governs when a repo harness is present."
+  ].join("\n");
+}

package/src/global/components/sdd-core.js

@@ -0,0 +1,17 @@
+import { join } from "node:path";
+
+export function buildSddCoreManagedSection(context, adapter, catalogEntry) {
+  const baseDir = join(context.componentsDir, "sdd-core");
+  const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+
+  return [
+    "### SDD Core",
+    "",
+    `- Workflow: ${join(baseDir, "workflow.md")}`,
+    `- Spec sizing: ${join(baseDir, "spec-sizing.md")}`,
+    `- Handoff rules: ${join(baseDir, "handoff.md")}`,
+    "- Classify work as basic, standard, or complex before implementing.",
+    "- No significant feature without a spec; no bug fix without a failing test first.",
+    adapterNote
+  ].filter(Boolean).join("\n");
+}

package/src/global/diff.js

@@ -0,0 +1,233 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { updateGlobalHarness } from "./global-installer.js";
+import { harnessHomePaths } from "./paths.js";
+import { readGlobalState } from "./state.js";
+import { buildStatusReport } from "./status.js";
+import { userOwnedContent } from "./managed-section.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function buildDiffReport(homeDir, {
+  packageRoot,
+  packageName,
+  cliVersion,
+  workspaceRoot = null
+}) {
+  const paths = harnessHomePaths(homeDir);
+  const state = await readGlobalState(paths.statePath);
+
+  if (!state) {
+    return {
+      homeDir,
+      installed: false,
+      status: "setup-required",
+      hasChanges: false,
+      summary: "No managed state found.",
+      nextAction: `Run "${formatCliCommand("setup --dry-run")}" to preview the initial managed plan.`,
+      changes: [],
+      preserved: []
+    };
+  }
+
+  const statusReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+  const needsRepair = statusReport.overall === "drift"
+    || statusReport.counts.missing > 0
+    || statusReport.counts.stale > 0;
+
+  if (!needsRepair) {
+    return {
+      homeDir,
+      installed: true,
+      status: "clean",
+      hasChanges: false,
+      summary: "No managed changes.",
+      nextAction: "Ecosystem in sync. No managed changes would be applied.",
+      changes: [],
+      preserved: await collectPreservedContent(homeDir, state)
+    };
+  }
+
+  const plan = await updateGlobalHarness({
+    packageRoot,
+    packageName,
+    cliVersion,
+    homeDir,
+    workspaceRoot,
+    dryRun: true
+  });
+
+  const changes = buildChangesFromPlan(plan);
+  const preserved = await collectPreservedForChanges(homeDir, plan);
+
+  return {
+    homeDir,
+    installed: true,
+    status: "drift",
+    hasChanges: true,
+    summary: `${changes.length} managed change(s) planned.`,
+    nextAction: `Run "${formatCliCommand("sync")}" to apply these managed repairs.`,
+    changes,
+    preserved
+  };
+}
+
+export async function summarizeInstallPreflight(homeDir, plan) {
+  const changes = buildChangesFromPlan({ ...plan, repairs: plan.repairs ?? [] });
+
+  for (const coreFile of plan.coreFiles ?? []) {
+    if (changes.some((change) => change.target === coreFile)) continue;
+    changes.push({
+      kind: "component_asset",
+      action: "create",
+      target: coreFile,
+      status: "planned",
+      detail: `Component asset would be written to ~/.harness/${coreFile}.`
+    });
+  }
+
+  const preserved = await collectPreservedForChanges(homeDir, plan);
+
+  return {
+    summary: changes.length > 0
+      ? `${changes.length} managed change(s) planned.`
+      : "No managed changes planned.",
+    changes,
+    preserved
+  };
+}
+
+export function buildChangesFromPlan(plan) {
+  const changes = [];
+
+  for (const repair of plan.repairs ?? []) {
+    changes.push({
+      kind: repair.category,
+      action: repairAction(repair),
+      target: repairTarget(repair),
+      status: repair.status,
+      detail: repair.detail
+    });
+  }
+
+  for (const configFile of plan.configsCreated ?? []) {
+    if (changes.some((change) => change.target === configFile)) continue;
+    changes.push({
+      kind: "config",
+      action: "create",
+      target: configFile,
+      status: "planned",
+      detail: `Managed config would be created at ~/${configFile}.`
+    });
+  }
+
+  for (const configFile of plan.configsUpdated ?? []) {
+    if (changes.some((change) => change.target === configFile)) continue;
+    changes.push({
+      kind: "config",
+      action: "update",
+      target: configFile,
+      status: "planned",
+      detail: `Managed config would be updated at ~/${configFile}.`
+    });
+  }
+
+  for (const configFile of plan.configsRepaired ?? []) {
+    if (changes.some((change) => change.target === configFile)) continue;
+    changes.push({
+      kind: "config",
+      action: "repair",
+      target: configFile,
+      status: "planned",
+      detail: `Managed section would be repaired at ~/${configFile}.`
+    });
+  }
+
+  return changes;
+}
+
+function repairAction(repair) {
+  if (repair.status === "missing") {
+    return repair.category === "managed_section" ? "create" : "repair";
+  }
+
+  if (repair.status === "stale") {
+    return repair.category === "managed_section" || repair.category === "component_section"
+      ? "replace"
+      : "repair";
+  }
+
+  return "repair";
+}
+
+function repairTarget(repair) {
+  if (repair.category === "component_asset") {
+    return repair.name.replace(/^~\//, "");
+  }
+
+  return repair.configFile ?? repair.name;
+}
+
+async function collectPreservedContent(homeDir, state) {
+  const preserved = [];
+  const configFiles = new Set(
+    (state.adapters ?? []).map((adapter) => adapter.configFile)
+  );
+
+  for (const configFile of configFiles) {
+    const entry = await readPreservedEntry(homeDir, configFile);
+    if (entry) preserved.push(entry);
+  }
+
+  return preserved;
+}
+
+async function collectPreservedForChanges(homeDir, plan) {
+  const configFiles = new Set([
+    ...(plan.configsCreated ?? []),
+    ...(plan.configsUpdated ?? []),
+    ...(plan.configsRepaired ?? []),
+    ...(plan.repairs ?? [])
+      .filter((repair) => repair.configFile)
+      .map((repair) => repair.configFile)
+  ]);
+
+  const preserved = [];
+
+  for (const configFile of configFiles) {
+    const entry = await readPreservedEntry(homeDir, configFile);
+    if (entry) preserved.push(entry);
+  }
+
+  return preserved;
+}
+
+async function readPreservedEntry(homeDir, configFile) {
+  const configPath = join(homeDir, configFile);
+  if (!existsSync(configPath)) return null;
+
+  const content = await readFile(configPath, "utf8");
+  const preserved = userOwnedContent(content).trim();
+
+  if (preserved.length === 0) return null;
+
+  return {
+    path: configFile,
+    preservedUserContent: preserved,
+    intact: true
+  };
+}
+
+export function buildDiffJson(report, { cliVersion = null } = {}) {
+  return {
+    ok: true,
+    installed: report.installed,
+    status: report.status,
+    hasChanges: report.hasChanges,
+    cliVersion,
+    summary: report.summary,
+    nextAction: report.nextAction,
+    changes: report.changes,
+    preserved: report.preserved
+  };
+}

package/src/global/drift.js

@@ -0,0 +1,264 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hashBuffer } from "../hash.js";
+import { buildManagedBody } from "./managed-body.js";
+import { hasManagedSection, upsertManagedSection } from "./managed-section.js";
+import { resolveComponent } from "./component-registry.js";
+import { resolveComponentTemplateDir } from "./component-paths.js";
+import { listAdapters } from "./registry.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function detectGlobalDrift({ homeDir, paths, state, packageRoot, workspaceRoot = null, context }) {
+  if (!state) {
+    return [{
+      name: "~/.harness/state.json",
+      status: "missing",
+      category: "state",
+      detail: `Not found. Run "${formatCliCommand("install")}" first.`
+    }];
+  }
+
+  const checks = [
+    stateMetadataCheck(state),
+    ...await componentAssetDrift({ paths, state, packageRoot, workspaceRoot, context }),
+    ...await managedSectionDrift({ homeDir, state, context }),
+    ...await componentSectionDrift({ homeDir, state, workspaceRoot, context }),
+    ...await adapterConfigDrift({ homeDir, state, context })
+  ];
+
+  return checks;
+}
+
+export function hasRepairableDrift(checks) {
+  return checks.some((check) => check.status === "missing" || check.status === "stale");
+}
+
+export function driftChecksToDoctor(checks) {
+  return checks;
+}
+
+function stateMetadataCheck(state) {
+  return {
+    name: "~/.harness/state.json",
+    status: "ok",
+    category: "state",
+    detail: `cliVersion=${state.cliVersion ?? "unknown"}, adapters=${state.adapters?.length ?? 0}, components=${state.components?.length ?? 0}`
+  };
+}
+
+async function componentAssetDrift({ paths, state, packageRoot, workspaceRoot, context }) {
+  const checks = [];
+  const installedComponents = context.components;
+
+  for (const component of installedComponents) {
+    const templateDir = resolveComponentTemplateDir(component, { packageRoot, workspaceRoot });
+    if (!existsSync(templateDir)) continue;
+
+    for (const assetFile of component.assetFiles) {
+      const relativePath = `components/${component.id}/${assetFile}`;
+      const templatePath = join(templateDir, assetFile);
+      const destinationPath = join(paths.root, relativePath);
+      const templateContent = await readFile(templatePath);
+      const expectedHash = hashBuffer(templateContent);
+
+      if (!existsSync(destinationPath)) {
+        checks.push({
+          name: `~/.harness/${relativePath}`,
+          status: "missing",
+          category: "component_asset",
+          componentId: component.id,
+          detail: "Component asset missing on disk."
+        });
+        continue;
+      }
+
+      const diskContent = await readFile(destinationPath);
+      const diskHash = hashBuffer(diskContent);
+      const trackedHash = state.coreFiles?.[relativePath];
+
+      if (diskHash !== expectedHash) {
+        checks.push({
+          name: `~/.harness/${relativePath}`,
+          status: "stale",
+          category: "component_asset",
+          componentId: component.id,
+          detail: `Asset hash drift (disk ${diskHash.slice(0, 8)} vs template ${expectedHash.slice(0, 8)}).`
+        });
+      } else if (trackedHash && trackedHash !== expectedHash) {
+        checks.push({
+          name: `~/.harness/${relativePath}`,
+          status: "stale",
+          category: "component_asset",
+          componentId: component.id,
+          detail: `State hash drift. Run ${formatCliCommand("sync")} to refresh metadata.`
+        });
+      } else {
+        checks.push({
+          name: `~/.harness/${relativePath}`,
+          status: "ok",
+          category: "component_asset",
+          componentId: component.id,
+          detail: `hash=${expectedHash.slice(0, 8)}`
+        });
+      }
+    }
+  }
+
+  return checks;
+}
+
+async function managedSectionDrift({ homeDir, state, context }) {
+  const checks = [];
+  const installedAdapterIds = new Set(state.adapters?.map((entry) => entry.id) ?? []);
+
+  for (const adapter of listAdapters()) {
+    if (!installedAdapterIds.has(adapter.id)) continue;
+
+    const configFile = adapter.assets.configFile;
+    const configPath = join(homeDir, configFile);
+    const checkName = `managed-section:${configFile}`;
+
+    if (!existsSync(configPath)) {
+      checks.push({
+        name: checkName,
+        status: "missing",
+        category: "managed_section",
+        adapterId: adapter.id,
+        configFile,
+        detail: `Installed adapter config missing: ~/${configFile}`
+      });
+      continue;
+    }
+
+    const content = await readFile(configPath, "utf8");
+    const expectedBody = buildManagedBody(context, { id: adapter.id, assets: adapter.assets });
+    const sectionStatus = classifyManagedSection(content, expectedBody);
+
+    checks.push({
+      name: checkName,
+      status: sectionStatus,
+      category: "managed_section",
+      adapterId: adapter.id,
+      configFile,
+      detail: managedSectionDetail(sectionStatus, configFile)
+    });
+  }
+
+  return checks;
+}
+
+async function componentSectionDrift({ homeDir, state, workspaceRoot, context }) {
+  const checks = [];
+
+  for (const stateEntry of state.components ?? []) {
+    const component = resolveComponent(stateEntry.id, { workspaceRoot });
+    const heading = componentSectionHeading(component);
+
+    for (const configFile of stateEntry.managedTargets ?? []) {
+      const configPath = join(homeDir, configFile);
+      const checkName = `component-section:${component.id}:${configFile}`;
+
+      if (!existsSync(configPath)) {
+        checks.push({
+          name: checkName,
+          status: "missing",
+          category: "component_section",
+          componentId: component.id,
+          configFile,
+          detail: `Managed target missing: ~/${configFile}`
+        });
+        continue;
+      }
+
+      const content = await readFile(configPath, "utf8");
+      let status = "ok";
+
+      if (!hasManagedSection(content)) {
+        status = "missing";
+      } else if (!content.includes(heading)) {
+        status = "stale";
+      }
+
+      checks.push({
+        name: checkName,
+        status,
+        category: "component_section",
+        componentId: component.id,
+        configFile,
+        detail: componentSectionDetail(status, component.id, configFile)
+      });
+    }
+  }
+
+  return checks;
+}
+
+async function adapterConfigDrift({ homeDir, state, context }) {
+  const checks = [];
+
+  for (const adapter of listAdapters()) {
+    const stateEntry = state.adapters?.find((entry) => entry.id === adapter.id);
+    const detected = adapter.detect(context);
+    const isRelevant = detected || Boolean(stateEntry);
+
+    if (!isRelevant) {
+      checks.push({
+        name: `agent:${adapter.id}`,
+        status: "warning",
+        category: "adapter",
+        adapterId: adapter.id,
+        detail: "Not detected on this machine."
+      });
+      continue;
+    }
+
+    if (!stateEntry) continue;
+
+    const configPath = join(homeDir, adapter.assets.configFile);
+    if (!existsSync(configPath)) {
+      checks.push({
+        name: `agent:${adapter.id}`,
+        status: "missing",
+        category: "adapter",
+        adapterId: adapter.id,
+        detail: `Installed in state but config missing: ~/${adapter.assets.configFile}`
+      });
+    }
+  }
+
+  return checks;
+}
+
+function classifyManagedSection(content, expectedBody) {
+  if (!hasManagedSection(content)) return "missing";
+
+  const { changed } = upsertManagedSection(content, expectedBody);
+  return changed ? "stale" : "ok";
+}
+
+function managedSectionDetail(status, configFile) {
+  switch (status) {
+    case "missing":
+      return `No managed section in ~/${configFile}. Run "${formatCliCommand("sync")}".`;
+    case "stale":
+      return `Stale managed section in ~/${configFile}. Run "${formatCliCommand("sync")}".`;
+    default:
+      return `Managed section in sync at ~/${configFile}`;
+  }
+}
+
+function componentSectionDetail(status, componentId, configFile) {
+  switch (status) {
+    case "missing":
+      return `Missing managed section for ${componentId} in ~/${configFile}`;
+    case "stale":
+      return `Stale managed section for ${componentId} in ~/${configFile}`;
+    default:
+      return `Component section in sync for ${componentId} in ~/${configFile}`;
+  }
+}
+
+function componentSectionHeading(component) {
+  return `### ${component.label}`;
+}