@kal-elsam/kairo-runtime 0.1.0

package/src/global/clack/theme.js

@@ -0,0 +1,145 @@
+import { styleText } from "node:util";
+import {
+  AGENT_HINTS,
+  BRAND,
+  getAgentLabel,
+  getAgentSymbol,
+  TOKENS,
+  WIZARD_COPY
+} from "../brand/index.js";
+import { formatCliCommand, PREFERRED_CLI } from "../brand/cli.js";
+
+export function brandIntroTitle() {
+  return WIZARD_COPY.introTitle;
+}
+
+export function paint(text, token) {
+  const color = TOKENS[token];
+  if (!color) return text;
+  return styleText(color, text);
+}
+
+export function formatSplashNote() {
+  return [
+    BRAND.splashLine,
+    "",
+    "Managed sections · drift repair · ~/.harness state"
+  ].join("\n");
+}
+
+export function formatAgentDetectCard({ adapters, detected }) {
+  const readyCount = detected.length;
+  const lines = [
+    `${readyCount} of ${adapters.length} agent roots found on this machine.`,
+    ""
+  ];
+
+  for (const adapter of adapters) {
+    const isReady = detected.includes(adapter.id);
+    const status = isReady ? AGENT_HINTS.ready : AGENT_HINTS.notDetected;
+    const marker = isReady ? paint("●", "success") : paint("○", "muted");
+    const label = getAgentLabel(adapter.id).padEnd(14, " ");
+    lines.push(`  ${getAgentSymbol(adapter.id)} ${label} ${marker} ${status}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function formatAgentMultiselectHint(adapterId, detected) {
+  if (detected.includes(adapterId)) {
+    return AGENT_HINTS.ready;
+  }
+  return AGENT_HINTS.managedLater;
+}
+
+export function formatComponentMultiselectHint(component) {
+  if (component.defaultEnabled) {
+    return "recommended";
+  }
+  return undefined;
+}
+
+function formatAgentList(agentIds) {
+  if (agentIds.length === 0) {
+    return "  none";
+  }
+  return agentIds.map((id) => `  ${getAgentLabel(id)}`).join("\n");
+}
+
+function formatComponentList(components, componentCatalog) {
+  if (components.length === 0) {
+    return `  ${WIZARD_COPY.coreOnlyLabel}`;
+  }
+
+  const labelById = new Map(componentCatalog.map((entry) => [entry.id, entry.label]));
+  return components
+    .map((id) => `  ${labelById.get(id) ?? id}`)
+    .join("\n");
+}
+
+function formatManagedWrite(change) {
+  const verb = change.action === "create"
+    ? "+"
+    : change.action === "repair"
+      ? "~"
+      : "↻";
+  return `  ${verb} ${change.target}`;
+}
+
+export function formatPreviewNote({ preview, componentCatalog = [] }) {
+  const { preflight, agents, components } = preview;
+  const lines = [
+    paint("Agents", "accent"),
+    formatAgentList(agents),
+    "",
+    paint("Components", "accent"),
+    formatComponentList(components, componentCatalog),
+    "",
+    paint("Managed writes", "accent")
+  ];
+
+  if (preflight.changes.length === 0) {
+    lines.push("  none — already in sync");
+  } else {
+    for (const change of preflight.changes) {
+      lines.push(formatManagedWrite(change));
+    }
+  }
+
+  lines.push("", paint("Preserved content", "accent"));
+  if (preflight.preserved.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const entry of preflight.preserved) {
+      lines.push(`  ${entry.path}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function formatResultNote(result, { dryRun = false, cliName = PREFERRED_CLI } = {}) {
+  const agentLabels = result.agents.map((id) => getAgentLabel(id)).join(", ");
+  const componentLine = result.components.length > 0
+    ? result.components.join(", ")
+    : WIZARD_COPY.coreOnlyLabel;
+
+  const lines = [
+    `State   ${result.stateRoot}`,
+    `Agents  ${agentLabels}`,
+    `Comps   ${componentLine}`,
+    `Writes  ${result.configsCreated.length} new · ${result.configsUpdated.length} updated`,
+    `${dryRun ? "Backup" : "Backups"}  ${dryRun ? "planned" : "created"}: ${result.backups.length}`,
+    "",
+    paint("Next steps", "accent"),
+    dryRun
+      ? `  ${formatCliCommand("setup --confirm", cliName)}   Apply this plan`
+      : `  ${formatCliCommand("status", cliName)}            Check ecosystem health`,
+    dryRun
+      ? `  ${formatCliCommand("setup --dry-run", cliName)}   Re-preview changes`
+      : `  ${formatCliCommand("doctor", cliName)}            Run health checks`,
+    dryRun ? "" : `  ${formatCliCommand("sync", cliName)}              Repair drift when needed`
+  ].filter((line) => line !== "");
+
+  return lines.join("\n");
+}

package/src/global/component-authoring.js

@@ -0,0 +1,121 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { COMPONENT_IDS } from "./component-registry.js";
+import {
+  hasWorkspaceCatalog,
+  loadWorkspaceComponentCatalog,
+  readWorkspaceCatalogDocument,
+  workspaceCatalogPath
+} from "./load-workspace-component-catalog.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+const COMPONENT_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+const DEFAULT_VERSION = "0.1.0";
+const DEFAULT_ASSET = "README.md";
+
+export function validateWorkspaceComponentsCatalog(workspaceRoot) {
+  const root = resolve(workspaceRoot);
+
+  if (!hasWorkspaceCatalog(root)) {
+    throw new Error("No workspace catalog at .harness/components/catalog.json");
+  }
+
+  const components = loadWorkspaceComponentCatalog(root, { bundledIds: COMPONENT_IDS });
+
+  return {
+    workspaceRoot: root,
+    catalogPath: workspaceCatalogPath(root),
+    components
+  };
+}
+
+export async function initWorkspaceComponent({ workspaceRoot, id, label }) {
+  const root = resolve(workspaceRoot);
+  const componentId = normalizeComponentId(id);
+  const componentLabel = normalizeLabel(label);
+
+  if (COMPONENT_IDS.includes(componentId)) {
+    throw new Error(`Component id "${componentId}" conflicts with a bundled component.`);
+  }
+
+  const componentsRoot = join(root, ".harness", "components");
+  const componentDir = join(componentsRoot, componentId);
+  const assetPath = join(componentDir, DEFAULT_ASSET);
+  const catalogPath = workspaceCatalogPath(root);
+  const catalog = hasWorkspaceCatalog(root)
+    ? readWorkspaceCatalogDocument(root)
+    : { components: [] };
+
+  if (!Array.isArray(catalog.components)) {
+    throw new Error("Workspace component catalog must declare a components array.");
+  }
+
+  if (catalog.components.some((entry) => entry.id === componentId)) {
+    throw new Error(`Workspace component "${componentId}" already exists.`);
+  }
+
+  if (existsSync(componentDir)) {
+    throw new Error(`Component directory already exists: .harness/components/${componentId}`);
+  }
+
+  const entry = {
+    id: componentId,
+    label: componentLabel,
+    version: DEFAULT_VERSION,
+    assetFiles: [DEFAULT_ASSET]
+  };
+
+  await mkdir(componentDir, { recursive: true });
+  await writeFile(assetPath, buildDefaultReadme(componentLabel, componentId));
+  catalog.components.push(entry);
+  await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
+
+  return {
+    workspaceRoot: root,
+    catalogPath,
+    componentDir,
+    assetPath,
+    entry
+  };
+}
+
+function normalizeComponentId(id) {
+  if (typeof id !== "string" || id.trim().length === 0) {
+    throw new Error("Component id is required.");
+  }
+
+  const componentId = id.trim();
+
+  if (!COMPONENT_ID_PATTERN.test(componentId)) {
+    throw new Error(
+      `Invalid component id "${id}". Use lowercase letters, digits, and hyphens (e.g. team-rules).`
+    );
+  }
+
+  return componentId;
+}
+
+function normalizeLabel(label) {
+  if (typeof label !== "string" || label.trim().length === 0) {
+    throw new Error(`Missing --label. Use: ${formatCliCommand('components init <id> --label "My Label"')}`);
+  }
+
+  return label.trim();
+}
+
+function buildDefaultReadme(label, id) {
+  return [
+    `# ${label}`,
+    "",
+    `Workspace component \`${id}\`.`,
+    "",
+    "Edit this file, then run:",
+    "",
+    "```bash",
+    formatCliCommand("components validate"),
+    formatCliCommand(`install --components ${id}`),
+    "```",
+    ""
+  ].join("\n");
+}

package/src/global/component-builders.js

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+import { buildOrchestratorManagedSection } from "./components/orchestrator.js";
+import { buildSddCoreManagedSection } from "./components/sdd-core.js";
+
+export const COMPONENT_BUILDERS = {
+  orchestrator: buildOrchestratorManagedSection,
+  "sdd-core": buildSddCoreManagedSection
+};
+
+export function resolveComponentBuilder(componentId) {
+  const builder = COMPONENT_BUILDERS[componentId];
+
+  if (!builder) {
+    throw new Error(`Missing managed section builder for component "${componentId}".`);
+  }
+
+  return builder;
+}
+
+export function createManagedSectionBuilder(componentId, catalogEntry) {
+  const builder = resolveComponentBuilder(componentId);
+
+  return (context, adapter) => builder(context, adapter, catalogEntry);
+}
+
+export function createWorkspaceManagedSectionBuilder(catalogEntry) {
+  return (context, adapter) => buildWorkspaceManagedSection(context, adapter, catalogEntry);
+}
+
+export function buildWorkspaceManagedSection(context, _adapter, catalogEntry) {
+  const baseDir = join(context.componentsDir, catalogEntry.id);
+  const lines = [`### ${catalogEntry.label}`, ""];
+
+  for (const asset of catalogEntry.assetFiles) {
+    lines.push(`- ${asset}: ${join(baseDir, asset)}`);
+  }
+
+  if (catalogEntry.instructions) {
+    lines.push("", catalogEntry.instructions);
+  }
+
+  return lines.join("\n");
+}

package/src/global/component-distribution.js

@@ -0,0 +1,270 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync } from "node:fs";
+import {
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  writeFile
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { isPathInside } from "./component-paths.js";
+import { COMPONENT_IDS } from "./component-registry.js";
+import {
+  hasWorkspaceCatalog,
+  loadWorkspaceComponentCatalog,
+  readWorkspaceCatalogDocument,
+  workspaceCatalogPath
+} from "./load-workspace-component-catalog.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function packWorkspaceComponent({ workspaceRoot, id, outPath }) {
+  const root = resolve(workspaceRoot);
+  const outputPath = resolve(outPath);
+
+  if (!id || typeof id !== "string") {
+    throw new Error("Component id is required.");
+  }
+
+  if (!outPath || typeof outPath !== "string") {
+    throw new Error(`Missing --out. Use: ${formatCliCommand("components pack <id> --out <file>")}`);
+  }
+
+  const components = loadWorkspaceComponentCatalog(root, { bundledIds: COMPONENT_IDS });
+  const component = components.find((entry) => entry.id === id);
+
+  if (!component) {
+    throw new Error(`Unknown workspace component "${id}".`);
+  }
+
+  const entry = serializeCatalogEntry(component);
+  const stagingDir = await mkdtemp(join(tmpdir(), "harness-pack-"));
+
+  try {
+    await writeFile(join(stagingDir, "catalog.json"), `${JSON.stringify({ components: [entry] }, null, 2)}\n`);
+
+    const sourceDir = join(root, ".harness", "components", component.id);
+    const stagedComponentDir = join(stagingDir, component.id);
+    await mkdir(stagedComponentDir, { recursive: true });
+
+    for (const assetFile of entry.assetFiles) {
+      const destination = join(stagedComponentDir, assetFile);
+      await mkdir(dirname(destination), { recursive: true });
+      await copyFile(join(sourceDir, assetFile), destination);
+    }
+
+    await mkdir(dirname(outputPath), { recursive: true });
+    runTar(["-czf", outputPath, "-C", stagingDir, "catalog.json", component.id]);
+
+    return {
+      outPath: outputPath,
+      entry
+    };
+  } finally {
+    await rm(stagingDir, { recursive: true, force: true });
+  }
+}
+
+export async function importWorkspaceComponent({ workspaceRoot, bundlePath }) {
+  const root = resolve(workspaceRoot);
+  const archivePath = resolve(bundlePath);
+
+  if (!existsSync(archivePath)) {
+    throw new Error(`Bundle not found: ${bundlePath}`);
+  }
+
+  assertSafeArchiveMembers(listTarMembers(archivePath));
+
+  const extractDir = await mkdtemp(join(tmpdir(), "harness-import-"));
+
+  try {
+    runTar(["-xzf", archivePath, "-C", extractDir]);
+
+    const catalogPath = join(extractDir, "catalog.json");
+    if (!existsSync(catalogPath)) {
+      throw new Error("Bundle is missing catalog.json.");
+    }
+
+    const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
+    if (!Array.isArray(catalog.components) || catalog.components.length !== 1) {
+      throw new Error("Component bundle must declare exactly one component.");
+    }
+
+    const entry = catalog.components[0];
+    assertCatalogEntryShape(entry);
+
+    if (COMPONENT_IDS.includes(entry.id)) {
+      throw new Error(`Workspace component "${entry.id}" conflicts with a bundled component.`);
+    }
+
+    const targetCatalog = hasWorkspaceCatalog(root)
+      ? readWorkspaceCatalogDocument(root)
+      : { components: [] };
+
+    if (!Array.isArray(targetCatalog.components)) {
+      throw new Error("Workspace component catalog must declare a components array.");
+    }
+
+    if (targetCatalog.components.some((candidate) => candidate.id === entry.id)) {
+      throw new Error(`Workspace component "${entry.id}" already exists.`);
+    }
+
+    const componentsRoot = join(root, ".harness", "components");
+    const targetComponentDir = join(componentsRoot, entry.id);
+
+    if (existsSync(targetComponentDir)) {
+      throw new Error(`Component directory already exists: .harness/components/${entry.id}`);
+    }
+
+    const validationRoot = await mkdtemp(join(tmpdir(), "harness-import-validate-"));
+
+    try {
+      const validationComponentsRoot = join(validationRoot, ".harness", "components");
+      const validationComponentDir = join(validationComponentsRoot, entry.id);
+      await mkdir(validationComponentDir, { recursive: true });
+      await writeFile(
+        join(validationComponentsRoot, "catalog.json"),
+        `${JSON.stringify({ components: [entry] }, null, 2)}\n`
+      );
+
+      for (const assetFile of entry.assetFiles) {
+        const sourcePath = join(extractDir, entry.id, assetFile);
+        assertDeclaredBundleAsset(sourcePath, entry.id, assetFile, extractDir);
+
+        const destination = join(validationComponentDir, assetFile);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(sourcePath, destination);
+      }
+
+      loadWorkspaceComponentCatalog(validationRoot, { bundledIds: COMPONENT_IDS });
+
+      await mkdir(targetComponentDir, { recursive: true });
+
+      for (const assetFile of entry.assetFiles) {
+        const destination = join(targetComponentDir, assetFile);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(join(extractDir, entry.id, assetFile), destination);
+      }
+
+      targetCatalog.components.push(entry);
+      await mkdir(componentsRoot, { recursive: true });
+      await writeFile(workspaceCatalogPath(root), `${JSON.stringify(targetCatalog, null, 2)}\n`);
+
+      loadWorkspaceComponentCatalog(root, { bundledIds: COMPONENT_IDS });
+    } finally {
+      await rm(validationRoot, { recursive: true, force: true });
+    }
+
+    return {
+      workspaceRoot: root,
+      catalogPath: workspaceCatalogPath(root),
+      entry
+    };
+  } finally {
+    await rm(extractDir, { recursive: true, force: true });
+  }
+}
+
+function serializeCatalogEntry(component) {
+  const entry = {
+    id: component.id,
+    label: component.label,
+    version: component.version,
+    assetFiles: [...component.assetFiles]
+  };
+
+  if (component.instructions) {
+    entry.instructions = component.instructions;
+  }
+
+  if (component.adapterHints && Object.keys(component.adapterHints).length > 0) {
+    entry.adapterHints = { ...component.adapterHints };
+  }
+
+  return entry;
+}
+
+function assertCatalogEntryShape(entry) {
+  for (const field of ["id", "label", "version", "assetFiles"]) {
+    if (entry?.[field] === undefined) {
+      throw new Error(`Bundle catalog entry is missing "${field}".`);
+    }
+  }
+
+  if (!Array.isArray(entry.assetFiles) || entry.assetFiles.length === 0) {
+    throw new Error(`Bundle component "${entry.id}" must declare at least one asset file.`);
+  }
+}
+
+function assertDeclaredBundleAsset(sourcePath, componentId, assetFile, extractDir) {
+  if (!existsSync(sourcePath)) {
+    throw new Error(`Bundle is missing declared asset "${assetFile}".`);
+  }
+
+  const stats = lstatSync(sourcePath);
+  if (stats.isSymbolicLink()) {
+    throw new Error(
+      `Bundle component "${componentId}" asset "${assetFile}" escapes the workspace via symlink.`
+    );
+  }
+
+  if (stats.isDirectory()) {
+    throw new Error(`Bundle component "${componentId}" asset "${assetFile}" must reference a file.`);
+  }
+
+  const allowedRoot = resolve(extractDir, componentId);
+  if (!isPathInside(allowedRoot, sourcePath)) {
+    throw new Error(
+      `Bundle component "${componentId}" asset "${assetFile}" escapes its component directory.`
+    );
+  }
+}
+
+function listTarMembers(archivePath) {
+  const stdout = runTar(["-tzf", archivePath]);
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function assertSafeArchiveMembers(members) {
+  if (members.length === 0) {
+    throw new Error("Bundle is empty.");
+  }
+
+  for (const member of members) {
+    const normalized = member.replaceAll("\\", "/").replace(/\/+$/, "");
+
+    if (!normalized) {
+      throw new Error(`Bundle contains an unsafe path "${member}".`);
+    }
+
+    if (
+      normalized.startsWith("/")
+      || normalized.includes("..")
+      || normalized.split("/").some((part) => part === ".." || part === "")
+    ) {
+      throw new Error(`Bundle contains an unsafe path "${member}".`);
+    }
+  }
+}
+
+function runTar(args) {
+  const result = spawnSync("tar", args, {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to run tar: ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || "tar failed").trim());
+  }
+
+  return result.stdout ?? "";
+}

package/src/global/component-installer.js

@@ -0,0 +1,106 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { hashBuffer } from "../hash.js";
+import { resolveComponentTemplateDir } from "./component-paths.js";
+
+export async function installComponentAssets({ packageRoot, workspaceRoot = null, paths, components, dryRun = false }) {
+  const coreFiles = {};
+
+  for (const component of components) {
+    const installed = await installComponentFiles({
+      packageRoot,
+      workspaceRoot,
+      paths,
+      component,
+      dryRun,
+      shouldRepair: () => true
+    });
+    Object.assign(coreFiles, installed);
+  }
+
+  return coreFiles;
+}
+
+export async function repairComponentAssets({
+  packageRoot,
+  workspaceRoot = null,
+  paths,
+  components,
+  state,
+  dryRun = false
+}) {
+  const coreFiles = { ...state?.coreFiles };
+  const repaired = [];
+  const unchanged = [];
+
+  for (const component of components) {
+    const installed = await installComponentFiles({
+      packageRoot,
+      workspaceRoot,
+      paths,
+      component,
+      dryRun,
+      shouldRepair: async (relativePath, destinationPath, templateContent) => {
+        const expectedHash = hashBuffer(templateContent);
+
+        if (!existsSync(destinationPath)) {
+          repaired.push(relativePath);
+          return true;
+        }
+
+        const diskContent = await readFile(destinationPath);
+        const diskHash = hashBuffer(diskContent);
+        const trackedHash = state?.coreFiles?.[relativePath];
+
+        if (diskHash !== expectedHash || trackedHash !== expectedHash) {
+          repaired.push(relativePath);
+          return true;
+        }
+
+        unchanged.push(relativePath);
+        return false;
+      }
+    });
+
+    Object.assign(coreFiles, installed);
+  }
+
+  return { coreFiles, repaired, unchanged };
+}
+
+async function installComponentFiles({
+  packageRoot,
+  workspaceRoot,
+  paths,
+  component,
+  dryRun,
+  shouldRepair
+}) {
+  const templateDir = resolveComponentTemplateDir(component, { packageRoot, workspaceRoot });
+  const coreFiles = {};
+
+  if (!existsSync(templateDir)) return coreFiles;
+
+  for (const assetFile of component.assetFiles) {
+    const sourcePath = join(templateDir, assetFile);
+    const relativePath = `components/${component.id}/${assetFile}`;
+    const destinationPath = join(paths.root, relativePath);
+    const content = await readFile(sourcePath);
+    const needsRepair = await shouldRepair(relativePath, destinationPath, content);
+
+    if (!needsRepair) {
+      coreFiles[relativePath] = hashBuffer(content);
+      continue;
+    }
+
+    if (!dryRun) {
+      await mkdir(dirname(destinationPath), { recursive: true });
+      await writeFile(destinationPath, content);
+    }
+
+    coreFiles[relativePath] = hashBuffer(content);
+  }
+
+  return coreFiles;
+}

package/src/global/component-paths.js

@@ -0,0 +1,22 @@
+import { join, resolve, sep } from "node:path";
+
+export function resolveComponentTemplateDir(component, { packageRoot, workspaceRoot }) {
+  if (component.source === "workspace") {
+    const root = component.workspaceRoot ?? workspaceRoot;
+
+    if (!root) {
+      throw new Error(`Workspace component "${component.id}" requires a workspace root.`);
+    }
+
+    return join(resolve(root), ".harness", "components", component.id);
+  }
+
+  return join(packageRoot, "global-template", "components", component.id);
+}
+
+export function isPathInside(parentPath, candidatePath) {
+  const parent = resolve(parentPath);
+  const candidate = resolve(candidatePath);
+
+  return candidate === parent || candidate.startsWith(`${parent}${sep}`);
+}