@kal-elsam/kairo-runtime 0.1.0

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

@@ -0,0 +1,123 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createWorkspaceManagedSectionBuilder } from "./component-builders.js";
+import { isPathInside } from "./component-paths.js";
+
+export function workspaceCatalogPath(workspaceRoot) {
+  return join(resolve(workspaceRoot), ".harness", "components", "catalog.json");
+}
+
+export function hasWorkspaceCatalog(workspaceRoot) {
+  if (!workspaceRoot) return false;
+  return existsSync(workspaceCatalogPath(workspaceRoot));
+}
+
+export function readWorkspaceCatalogDocument(workspaceRoot) {
+  return JSON.parse(readFileSync(workspaceCatalogPath(workspaceRoot), "utf8"));
+}
+
+export function loadWorkspaceComponentCatalog(workspaceRoot, { bundledIds = [] } = {}) {
+  if (!workspaceRoot || !hasWorkspaceCatalog(workspaceRoot)) {
+    return [];
+  }
+
+  const resolvedRoot = resolve(workspaceRoot);
+  const catalog = readWorkspaceCatalogDocument(resolvedRoot);
+  const componentsRoot = join(resolvedRoot, ".harness", "components");
+  const entries = catalog.components;
+
+  if (!Array.isArray(entries)) {
+    throw new Error("Workspace component catalog must declare a components array.");
+  }
+
+  const seen = new Set();
+  const components = [];
+
+  for (const entry of entries) {
+    validateWorkspaceEntry(entry, { componentsRoot, workspaceRoot: resolvedRoot, bundledIds, seen });
+    seen.add(entry.id);
+
+    components.push({
+      id: entry.id,
+      label: entry.label,
+      version: entry.version,
+      source: "workspace",
+      defaultEnabled: false,
+      assetFiles: [...entry.assetFiles],
+      adapterHints: { ...(entry.adapterHints ?? {}) },
+      instructions: entry.instructions ?? null,
+      workspaceRoot: resolvedRoot,
+      buildManagedSection: createWorkspaceManagedSectionBuilder(entry)
+    });
+  }
+
+  return components;
+}
+
+function validateWorkspaceEntry(entry, { componentsRoot, workspaceRoot, bundledIds, seen }) {
+  const required = ["id", "label", "version", "assetFiles"];
+
+  for (const field of required) {
+    if (entry[field] === undefined) {
+      throw new Error(`Workspace component catalog entry is missing "${field}".`);
+    }
+  }
+
+  if (!Array.isArray(entry.assetFiles) || entry.assetFiles.length === 0) {
+    throw new Error(`Workspace component "${entry.id}" must declare at least one asset file.`);
+  }
+
+  if (bundledIds.includes(entry.id)) {
+    throw new Error(`Workspace component "${entry.id}" conflicts with a bundled component.`);
+  }
+
+  if (seen.has(entry.id)) {
+    throw new Error(`Duplicate workspace component id "${entry.id}".`);
+  }
+
+  const componentDir = join(componentsRoot, entry.id);
+
+  for (const assetFile of entry.assetFiles) {
+    validateAssetFile(assetFile, { componentDir, componentId: entry.id, workspaceRoot });
+  }
+}
+
+function validateAssetFile(assetFile, { componentDir, componentId, workspaceRoot }) {
+  if (typeof assetFile !== "string" || assetFile.length === 0) {
+    throw new Error(`Workspace component "${componentId}" has an invalid asset path.`);
+  }
+
+  if (assetFile.startsWith("/") || assetFile.includes("\\") || assetFile.includes("..")) {
+    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" must be a relative path without "..".`);
+  }
+
+  if (assetFile.endsWith("/")) {
+    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" must reference a file.`);
+  }
+
+  const assetPath = join(componentDir, ...assetFile.split("/"));
+  const normalized = resolve(assetPath);
+
+  if (!isPathInside(componentDir, normalized)) {
+    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" escapes its component directory.`);
+  }
+
+  if (!existsSync(assetPath)) {
+    throw new Error(`Workspace component "${componentId}" is missing asset "${assetFile}".`);
+  }
+
+  if (lstatSync(assetPath).isDirectory()) {
+    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" must reference a file.`);
+  }
+
+  assertAssetStaysInWorkspace(assetPath, workspaceRoot, componentId, assetFile);
+}
+
+function assertAssetStaysInWorkspace(assetPath, workspaceRoot, componentId, assetFile) {
+  const workspaceReal = realpathSync(workspaceRoot);
+  const assetReal = realpathSync(assetPath);
+
+  if (!isPathInside(workspaceReal, assetReal)) {
+    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" escapes the workspace via symlink.`);
+  }
+}

package/src/global/managed-body.js

@@ -0,0 +1,28 @@
+import { formatCliCommand } from "./brand/cli.js";
+import { BRAND } from "./brand/index.js";
+
+export function buildManagedBody(context, adapter) {
+  const sections = [
+    `## ${BRAND.displayName} (managed)`,
+    "",
+    `Managed by \`${context.packageName}\`. Content inside these markers is refreshed by`,
+    `\`${formatCliCommand("sync")}\`. Everything outside the markers is yours and is preserved.`
+  ];
+
+  if (context.components.length === 0) {
+    sections.push("", "_No optional components installed. Core plumbing only._");
+    return sections.join("\n");
+  }
+
+  for (const component of context.components) {
+    sections.push("", component.buildManagedSection(context, adapter));
+  }
+
+  sections.push(
+    "",
+    `- Run \`${formatCliCommand("doctor")}\` to check ecosystem health.`,
+    `- Run \`${formatCliCommand("uninstall")}\` to remove managed sections safely.`
+  );
+
+  return sections.join("\n");
+}

package/src/global/managed-config-adapter.js

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { backupFileBeforeChange } from "./backups.js";
+import { buildManagedBody } from "./managed-body.js";
+import { hasManagedSection, removeManagedSection, upsertManagedSection } from "./managed-section.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export function createManagedConfigAdapter({ id, label, rootDir, configFile }) {
+  const assets = {
+    rootDir,
+    configFile,
+    managedTargets: [configFile]
+  };
+
+  return {
+    id,
+    label,
+    assets,
+
+    detect(context) {
+      return existsSync(join(context.homeDir, rootDir));
+    },
+
+    plan(context) {
+      const configPath = join(context.homeDir, configFile);
+      const exists = existsSync(configPath);
+      const current = exists ? readFileSync(configPath, "utf8") : "";
+      const body = buildManagedBody(context, { id, assets });
+      const { changed } = upsertManagedSection(current, body);
+
+      let action = "unchanged";
+      if (changed) action = exists ? "update" : "create";
+
+      return {
+        adapterId: id,
+        configFile,
+        configPath,
+        action,
+        exists,
+        backupNeeded: exists && changed
+      };
+    },
+
+    async apply(context, plan) {
+      if (plan.action === "unchanged") {
+        return { configFile, action: "unchanged", backupPath: null };
+      }
+
+      const current = plan.exists ? await readFile(plan.configPath, "utf8") : "";
+      const body = buildManagedBody(context, { id, assets });
+      const { content: next } = upsertManagedSection(current, body);
+      let backupPath = null;
+
+      if (plan.backupNeeded) {
+        backupPath = await backupFileBeforeChange({
+          backupsDir: context.paths.backupsDir,
+          homeDir: context.homeDir,
+          filePath: plan.configPath,
+          timestamp: context.timestamp,
+          dryRun: context.dryRun
+        });
+      }
+
+      if (!context.dryRun) {
+        await mkdir(dirname(plan.configPath), { recursive: true });
+        await writeFile(plan.configPath, next, "utf8");
+      }
+
+      return { configFile, action: plan.action, backupPath };
+    },
+
+    async doctor(context, stateEntry) {
+      const installed = Boolean(stateEntry);
+      const detected = this.detect(context);
+      const isRelevant = detected || installed;
+
+      if (!isRelevant) {
+        return {
+          name: `agent:${id}`,
+          status: "info",
+          detail: "Not detected on this machine."
+        };
+      }
+
+      const configPath = join(context.homeDir, configFile);
+      if (!existsSync(configPath)) {
+        return {
+          name: `agent:${id}`,
+          status: installed ? "missing" : "warning",
+          detail: `Config not found: ~/${configFile}`
+        };
+      }
+
+      const content = await readFile(configPath, "utf8");
+      const managed = hasManagedSection(content);
+
+      return {
+        name: `agent:${id}`,
+        status: managed ? "ok" : "warning",
+        detail: managed
+          ? `Managed section present in ~/${configFile}`
+          : `No managed section in ~/${configFile}. Run "${formatCliCommand("install")}".`
+      };
+    },
+
+    async uninstall(context, stateEntry) {
+      const configPath = join(context.homeDir, configFile);
+      if (!existsSync(configPath)) {
+        return { configFile, cleaned: false, backupPath: null };
+      }
+
+      const content = await readFile(configPath, "utf8");
+      const { content: cleaned, removed } = removeManagedSection(content);
+      if (!removed) {
+        return { configFile, cleaned: false, backupPath: null };
+      }
+
+      const backupPath = await backupFileBeforeChange({
+        backupsDir: context.paths.backupsDir,
+        homeDir: context.homeDir,
+        filePath: configPath,
+        timestamp: context.timestamp,
+        dryRun: context.dryRun
+      });
+
+      if (!context.dryRun) {
+        await writeFile(configPath, cleaned, "utf8");
+      }
+
+      return { configFile, cleaned: true, backupPath };
+    }
+  };
+}

package/src/global/managed-section.js

@@ -0,0 +1,73 @@
+export const SECTION_START = "<!-- harness:managed:start -->";
+export const SECTION_END = "<!-- harness:managed:end -->";
+
+export function hasManagedSection(content) {
+  const start = content.indexOf(SECTION_START);
+  const end = content.indexOf(SECTION_END);
+  return start !== -1 && end !== -1 && end > start;
+}
+
+export function extractManagedBody(content) {
+  if (!hasManagedSection(content)) return null;
+
+  const start = content.indexOf(SECTION_START) + SECTION_START.length;
+  const end = content.indexOf(SECTION_END);
+
+  return content.slice(start, end).replace(/^\n/, "").replace(/\n$/, "");
+}
+
+export function buildManagedBlock(body) {
+  return `${SECTION_START}\n${body.replace(/\s+$/, "")}\n${SECTION_END}\n`;
+}
+
+export function upsertManagedSection(content, body) {
+  const block = buildManagedBlock(body);
+
+  if (!hasManagedSection(content)) {
+    if (content.trim() === "") {
+      return { content: block, changed: block !== content, hadSection: false };
+    }
+
+    const next = `${content.replace(/\s+$/, "")}\n\n${block}`;
+    return { content: next, changed: true, hadSection: false };
+  }
+
+  const start = content.indexOf(SECTION_START);
+  const end = blockEndIndex(content);
+  const next = content.slice(0, start) + block + content.slice(end);
+
+  return { content: next, changed: next !== content, hadSection: true };
+}
+
+export function removeManagedSection(content) {
+  if (!hasManagedSection(content)) {
+    return { content, removed: false };
+  }
+
+  const start = content.indexOf(SECTION_START);
+  const end = blockEndIndex(content);
+  const before = content.slice(0, start).replace(/\s+$/, "");
+  const after = content.slice(end).replace(/^\s+/, "");
+
+  if (!before && !after) return { content: "", removed: true };
+  if (!before) return { content: after, removed: true };
+  if (!after) return { content: `${before}\n`, removed: true };
+
+  return { content: `${before}\n\n${after}`, removed: true };
+}
+
+export function userOwnedContent(content) {
+  if (!hasManagedSection(content)) return content;
+
+  const start = content.indexOf(SECTION_START);
+  const end = blockEndIndex(content);
+  const before = content.slice(0, start);
+  const after = content.slice(end);
+
+  return `${before}${after}`;
+}
+
+function blockEndIndex(content) {
+  const end = content.indexOf(SECTION_END) + SECTION_END.length;
+  return content[end] === "\n" ? end + 1 : end;
+}

package/src/global/npm-registry.js

@@ -0,0 +1,25 @@
+export async function fetchPublishedVersion(packageName, fetchJson = defaultFetchJson) {
+  const testVersion = process.env.HARNESS_TEST_LATEST_VERSION?.trim();
+  if (testVersion) {
+    return testVersion;
+  }
+
+  const encodedPackage = encodeURIComponent(packageName);
+  const meta = await fetchJson(`https://registry.npmjs.org/${encodedPackage}/latest`);
+
+  if (!meta?.version) {
+    throw new Error(`Could not resolve latest version for ${packageName}.`);
+  }
+
+  return meta.version;
+}
+
+async function defaultFetchJson(url) {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+  }
+
+  return response.json();
+}

package/src/global/paths.js

@@ -0,0 +1,22 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const HARNESS_DIR_NAME = ".harness";
+
+export function resolveHomeDir(env = process.env) {
+  return env.HARNESS_HOME ?? homedir();
+}
+
+export function harnessHomePaths(homeDir) {
+  const root = join(homeDir, HARNESS_DIR_NAME);
+
+  return {
+    homeDir,
+    root,
+    statePath: join(root, "state.json"),
+    policyPath: join(root, "policy.json"),
+    historyPath: join(root, "history.jsonl"),
+    coreDir: join(root, "core"),
+    backupsDir: join(root, "backups")
+  };
+}