openship 0.1.0 → 0.1.1

package/packages/adapters/src/system/checks.ts

@@ -0,0 +1,228 @@
+/**
+ * Component health checks — detect installed binaries and running services.
+ *
+ * All checks run through a CommandExecutor, so they work both locally
+ * and on remote servers via SSH. Checks are fast, non-destructive, and
+ * safe to run repeatedly.
+ *
+ * In normal operation, checks run ONCE during setup — the result is
+ * cached in SetupStateStore. Subsequent operations read cached state
+ * instead of re-running checks (see setup.ts).
+ */
+
+import type { CommandExecutor } from "../types";
+import type { ComponentStatus } from "./types";
+import { systemCatalog } from "./catalog";
+import { getSystemComponentDefinition, SYSTEM_COMPONENTS } from "./components";
+import { formatDuration, systemDebug } from "./debug";
+import { isRemoteConnectionError } from "./errors";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Run a command via executor, return stdout or null on failure. */
+async function tryExec(
+  executor: CommandExecutor,
+  command: string,
+): Promise<string | null> {
+  const startedAt = Date.now();
+  systemDebug("checks", `exec:start ${command}`);
+  try {
+    const result = await executor.exec(command, { timeout: 10_000 });
+    systemDebug(
+      "checks",
+      `exec:ok ${command} (${formatDuration(startedAt)})`,
+    );
+    return result;
+  } catch (err) {
+    if (isRemoteConnectionError(err)) {
+      systemDebug(
+        "checks",
+        `exec:abort ${command} (${formatDuration(startedAt)}) ${err instanceof Error ? err.message : String(err)}`,
+      );
+      throw err;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    systemDebug(
+      "checks",
+      `exec:fail ${command} (${formatDuration(startedAt)}) ${msg}`,
+    );
+    return null;
+  }
+}
+
+function healthy(
+  name: string,
+  version: string,
+  running?: boolean,
+): ComponentStatus {
+  const component = getSystemComponentDefinition(name);
+  return {
+    name,
+    label: component.label,
+    description: component.description,
+    installable: component.installable,
+    installed: true,
+    version,
+    running,
+    healthy: running !== undefined ? running : true,
+    message: running
+      ? `${name} ${version} — running`
+      : `${name} ${version} — installed`,
+  };
+}
+
+function unhealthy(
+  name: string,
+  message: string,
+  opts?: { version?: string; running?: boolean },
+): ComponentStatus {
+  const component = getSystemComponentDefinition(name);
+  return {
+    name,
+    label: component.label,
+    description: component.description,
+    installable: component.installable,
+    installed: !!opts?.version,
+    version: opts?.version,
+    running: opts?.running,
+    healthy: false,
+    message,
+  };
+}
+
+// ─── Individual checks ──────────────────────────────────────────────────────
+
+export async function checkDocker(
+  executor: CommandExecutor,
+): Promise<ComponentStatus> {
+  const startedAt = Date.now();
+  const recipe = systemCatalog.checks.docker;
+  const version = await tryExec(executor, recipe.versionCommand);
+  if (!version) {
+    systemDebug("checks", `docker:missing (${formatDuration(startedAt)})`);
+    return unhealthy("docker", recipe.missingMessage);
+  }
+
+  const parsed = recipe.parseVersion(version);
+
+  const info = await tryExec(executor, recipe.daemonCommand!);
+  if (!info) {
+    systemDebug("checks", `docker:not-running (${formatDuration(startedAt)})`);
+    return unhealthy("docker", recipe.notRunningMessage!, {
+      version: parsed,
+      running: false,
+    });
+  }
+
+  systemDebug("checks", `docker:healthy (${formatDuration(startedAt)})`);
+  return healthy("docker", parsed, true);
+}
+
+export async function checkTraefik(
+  executor: CommandExecutor,
+): Promise<ComponentStatus> {
+  const startedAt = Date.now();
+  const recipe = systemCatalog.checks.traefik;
+  const version = await tryExec(executor, recipe.versionCommand);
+
+  let parsed: string | undefined;
+  if (version) {
+    parsed = recipe.parseVersion(version);
+  }
+
+  const runningChecks = await Promise.all(
+    recipe.runningCommands!.map((command) => tryExec(executor, command)),
+  );
+  const running = runningChecks.some(Boolean);
+
+  if (!parsed && !running) {
+    systemDebug("checks", `traefik:missing (${formatDuration(startedAt)})`);
+    return unhealthy("traefik", recipe.missingMessage);
+  }
+
+  if (!running) {
+    systemDebug("checks", `traefik:not-running (${formatDuration(startedAt)})`);
+    return unhealthy("traefik", recipe.notRunningMessage!, {
+      version: parsed,
+      running: false,
+    });
+  }
+
+  systemDebug("checks", `traefik:healthy (${formatDuration(startedAt)})`);
+  return healthy("traefik", parsed ?? "unknown", true);
+}
+
+export async function checkGit(
+  executor: CommandExecutor,
+): Promise<ComponentStatus> {
+  const startedAt = Date.now();
+  const recipe = systemCatalog.checks.git;
+  const version = await tryExec(executor, recipe.versionCommand);
+  if (!version) {
+    systemDebug("checks", `git:missing (${formatDuration(startedAt)})`);
+    return unhealthy("git", recipe.missingMessage);
+  }
+  const parsed = recipe.parseVersion(version);
+  systemDebug("checks", `git:healthy (${formatDuration(startedAt)})`);
+  return healthy("git", parsed);
+}
+
+export async function checkNode(
+  executor: CommandExecutor,
+): Promise<ComponentStatus> {
+  const startedAt = Date.now();
+  const recipe = systemCatalog.checks.node;
+  const version = await tryExec(executor, recipe.versionCommand);
+  if (!version) {
+    systemDebug("checks", `node:missing (${formatDuration(startedAt)})`);
+    return unhealthy("node", recipe.missingMessage);
+  }
+  systemDebug("checks", `node:healthy (${formatDuration(startedAt)})`);
+  return healthy("node", recipe.parseVersion(version));
+}
+
+// ─── Registry ────────────────────────────────────────────────────────────────
+
+type CheckFn = (executor: CommandExecutor) => Promise<ComponentStatus>;
+
+export const COMPONENT_CHECKS: Record<string, CheckFn> = {
+  docker: checkDocker,
+  traefik: checkTraefik,
+  git: checkGit,
+  node: checkNode,
+};
+
+/** Run every registered check in parallel. */
+export async function checkAll(
+  executor: CommandExecutor,
+): Promise<ComponentStatus[]> {
+  const startedAt = Date.now();
+  const entries = SYSTEM_COMPONENTS
+    .map((component) => [component.name, COMPONENT_CHECKS[component.name]] as const)
+    .filter((entry): entry is readonly [string, CheckFn] => Boolean(entry[1]));
+  systemDebug(
+    "checks",
+    `checkAll:start [${entries.map(([name]) => name).join(", ")}]`,
+  );
+  const result = await Promise.all(entries.map(([, fn]) => fn(executor)));
+  systemDebug("checks", `checkAll:done (${formatDuration(startedAt)})`);
+  return result;
+}
+
+/** Run checks for a specific set of components. */
+export async function checkComponents(
+  executor: CommandExecutor,
+  names: string[],
+): Promise<ComponentStatus[]> {
+  const startedAt = Date.now();
+  const fns = names
+    .map((name) => COMPONENT_CHECKS[name])
+    .filter(Boolean);
+  systemDebug("checks", `checkComponents:start [${names.join(", ")}]`);
+  const result = await Promise.all(fns.map((fn) => fn(executor)));
+  systemDebug(
+    "checks",
+    `checkComponents:done [${names.join(", ")}] (${formatDuration(startedAt)})`,
+  );
+  return result;
+}

package/packages/adapters/src/system/components.ts

@@ -0,0 +1,45 @@
+import type { SystemComponentDefinition } from "./types";
+
+export const SYSTEM_COMPONENTS: SystemComponentDefinition[] = [
+  {
+    name: "docker",
+    label: "Docker",
+    description: "Container runtime for deployments",
+    installable: true,
+  },
+  {
+    name: "traefik",
+    label: "Traefik",
+    description: "Reverse proxy and SSL certificates",
+    installable: true,
+  },
+  {
+    name: "git",
+    label: "Git",
+    description: "Version control for source code",
+    installable: true,
+  },
+  {
+    name: "node",
+    label: "Node.js",
+    description: "JavaScript runtime for build and app tasks",
+    installable: true,
+  },
+];
+
+export const SYSTEM_COMPONENTS_BY_NAME = new Map(
+  SYSTEM_COMPONENTS.map((component) => [component.name, component]),
+);
+
+export function getSystemComponentDefinition(
+  name: string,
+): SystemComponentDefinition {
+  return (
+    SYSTEM_COMPONENTS_BY_NAME.get(name) ?? {
+      name,
+      label: name,
+      description: `${name} component`,
+      installable: false,
+    }
+  );
+}

package/packages/adapters/src/system/debug.ts

@@ -0,0 +1,18 @@
+function isTruthy(value: string | undefined): boolean {
+  if (!value) return false;
+  return ["1", "true", "yes", "on", "debug"].includes(value.toLowerCase());
+}
+
+export function isSystemDebugEnabled(): boolean {
+  return isTruthy(process.env.SYSTEM_DEBUG_LOGS);
+}
+
+export function systemDebug(scope: string, message: string): void {
+  if (!isSystemDebugEnabled()) return;
+  const timestamp = new Date().toISOString();
+  console.log(`[system-debug] ${timestamp} [${scope}] ${message}`);
+}
+
+export function formatDuration(startMs: number): string {
+  return `${Date.now() - startMs}ms`;
+}

package/packages/adapters/src/system/environment.ts

@@ -0,0 +1,168 @@
+import type { CommandExecutor } from "../types";
+import { formatDuration, systemDebug } from "./debug";
+import { isRemoteConnectionError } from "./errors";
+
+export type SystemOs = "linux" | "darwin" | "unknown";
+export type SystemArch = "amd64" | "arm64" | "unknown";
+export type SystemPackageManager = "apt" | "dnf" | "yum" | "brew" | "none";
+export type SystemServiceManager = "systemd" | "launchd" | "none";
+export type LinuxDistro =
+  | "ubuntu"
+  | "debian"
+  | "fedora"
+  | "rhel"
+  | "centos"
+  | "alpine"
+  | "unknown";
+
+export interface EnvironmentProfile {
+  os: SystemOs;
+  arch: SystemArch;
+  distro: LinuxDistro | null;
+  packageManager: SystemPackageManager;
+  serviceManager: SystemServiceManager;
+}
+
+const profileCache = new WeakMap<CommandExecutor, Promise<EnvironmentProfile>>();
+
+async function execSafe(
+  executor: CommandExecutor,
+  command: string,
+  timeout = 5_000,
+): Promise<string | null> {
+  const startedAt = Date.now();
+  systemDebug("environment", `exec:start ${command}`);
+  try {
+    const result = await executor.exec(command, { timeout });
+    systemDebug(
+      "environment",
+      `exec:ok ${command} (${formatDuration(startedAt)})`,
+    );
+    return result;
+  } catch (err) {
+    if (isRemoteConnectionError(err)) {
+      systemDebug(
+        "environment",
+        `exec:abort ${command} (${formatDuration(startedAt)}) ${err instanceof Error ? err.message : String(err)}`,
+      );
+      throw err;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    systemDebug(
+      "environment",
+      `exec:fail ${command} (${formatDuration(startedAt)}) ${msg}`,
+    );
+    return null;
+  }
+}
+
+function parseOs(uname: string | null): SystemOs {
+  const value = uname?.trim().toLowerCase();
+  if (value === "linux") return "linux";
+  if (value === "darwin") return "darwin";
+  return "unknown";
+}
+
+function parseArch(uname: string | null): SystemArch {
+  const value = uname?.trim().toLowerCase() ?? "";
+  if (["x86_64", "amd64"].includes(value)) return "amd64";
+  if (["aarch64", "arm64"].includes(value)) return "arm64";
+  return "unknown";
+}
+
+function parseDistro(osRelease: string | null): LinuxDistro | null {
+  if (!osRelease) return null;
+
+  const lower = osRelease.toLowerCase();
+  const match = lower.match(/^id=(.+)$/m);
+  const id = match?.[1]?.replaceAll('"', "").trim();
+
+  switch (id) {
+    case "ubuntu":
+      return "ubuntu";
+    case "debian":
+      return "debian";
+    case "fedora":
+      return "fedora";
+    case "rhel":
+    case "rhel server":
+      return "rhel";
+    case "centos":
+      return "centos";
+    case "alpine":
+      return "alpine";
+    default:
+      return "unknown";
+  }
+}
+
+async function detectPackageManager(
+  executor: CommandExecutor,
+): Promise<SystemPackageManager> {
+  const checks: Array<[SystemPackageManager, string]> = [
+    ["apt", "command -v apt-get"],
+    ["dnf", "command -v dnf"],
+    ["yum", "command -v yum"],
+    ["brew", "command -v brew"],
+  ];
+
+  for (const [pm, command] of checks) {
+    if (await execSafe(executor, command)) return pm;
+  }
+
+  return "none";
+}
+
+async function detectServiceManager(
+  executor: CommandExecutor,
+): Promise<SystemServiceManager> {
+  if (await execSafe(executor, "command -v systemctl")) return "systemd";
+  if (await execSafe(executor, "command -v launchctl")) return "launchd";
+  return "none";
+}
+
+async function detectProfile(
+  executor: CommandExecutor,
+): Promise<EnvironmentProfile> {
+  const startedAt = Date.now();
+  systemDebug("environment", "detect:start");
+  const [unameOs, unameArch, osRelease, packageManager, serviceManager] =
+    await Promise.all([
+      execSafe(executor, "uname -s"),
+      execSafe(executor, "uname -m"),
+      execSafe(executor, "cat /etc/os-release"),
+      detectPackageManager(executor),
+      detectServiceManager(executor),
+    ]);
+
+  const os = parseOs(unameOs);
+
+  const profile = {
+    os,
+    arch: parseArch(unameArch),
+    distro: os === "linux" ? parseDistro(osRelease) : null,
+    packageManager,
+    serviceManager,
+  };
+
+  systemDebug(
+    "environment",
+    `detect:done (${formatDuration(startedAt)}) ${JSON.stringify(profile)}`,
+  );
+
+  return profile;
+}
+
+export async function resolveEnvironment(
+  executor: CommandExecutor,
+): Promise<EnvironmentProfile> {
+  let promise = profileCache.get(executor);
+  if (!promise) {
+    systemDebug("environment", "cache:miss");
+    promise = detectProfile(executor);
+    profileCache.set(executor, promise);
+  } else {
+    systemDebug("environment", "cache:hit");
+  }
+  return promise;
+}

package/packages/adapters/src/system/errors.ts

@@ -0,0 +1,34 @@
+const SSH_AUTH_ERROR_PATTERNS = [
+  "All configured authentication methods failed",
+];
+
+const RETRYABLE_CONNECTION_ERROR_PATTERNS = [
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "Timed out",
+  "Not connected",
+  "Connection lost",
+  "read ECONNRESET",
+  "Handshake failed",
+  "keepalive timeout",
+  "SSH connection closed before ready",
+];
+
+export function isSshAuthError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return SSH_AUTH_ERROR_PATTERNS.some((pattern) => err.message.includes(pattern));
+}
+
+export function isRetryableRemoteConnectionError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return RETRYABLE_CONNECTION_ERROR_PATTERNS.some((pattern) =>
+    err.message.includes(pattern),
+  );
+}
+
+export function isRemoteConnectionError(err: unknown): boolean {
+  return isSshAuthError(err) || isRetryableRemoteConnectionError(err);
+}