@duypham93/openkit 0.2.0

package/src/install/materialize.js

@@ -0,0 +1,158 @@
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { createInstallState } from "./install-state.js"
+import { applyOpenKitMergePolicy } from "./merge-policy.js"
+import { createMaterializationConflict, qualifyMergeConflicts } from "./conflicts.js"
+
+const ROOT_MANIFEST_ASSET_ID = "runtime.opencode-manifest"
+const ROOT_MANIFEST_PATH = "opencode.json"
+const INSTALL_STATE_ASSET_ID = "runtime.install-state"
+const INSTALL_STATE_PATH = ".openkit/openkit-install.json"
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url))
+const BUNDLE_ROOT = path.resolve(MODULE_DIR, "../..")
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"))
+}
+
+function readExistingJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null
+  }
+
+  return readJson(filePath)
+}
+
+function readTemplate(relativePath) {
+  return readJson(path.join(BUNDLE_ROOT, relativePath))
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8")
+}
+
+function removeFileIfPresent(filePath) {
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath)
+  }
+}
+
+export function materializeInstall(projectRoot, { kitVersion = "0.1.0", now } = {}) {
+  const desiredRootManifest = readTemplate("assets/opencode.json.template")
+  const rootManifestPath = path.join(projectRoot, ROOT_MANIFEST_PATH)
+  const installStatePath = path.join(projectRoot, INSTALL_STATE_PATH)
+  const existingRootManifest = readExistingJson(rootManifestPath)
+  const existingInstallState = readExistingJson(installStatePath)
+
+  let rootManifestToWrite = desiredRootManifest
+  let rootManifestManagedStatus = "materialized"
+  let adoptedAssets = []
+  const warnings = []
+  let conflicts = []
+
+  if (existingRootManifest !== null) {
+    const mergeResult = applyOpenKitMergePolicy({
+      currentConfig: existingRootManifest,
+      desiredConfig: desiredRootManifest,
+    })
+
+    conflicts = qualifyMergeConflicts(mergeResult.conflicts, ROOT_MANIFEST_ASSET_ID, ROOT_MANIFEST_PATH)
+
+    if (conflicts.length === 0) {
+      rootManifestToWrite = mergeResult.config
+    } else {
+      rootManifestToWrite = existingRootManifest
+      rootManifestManagedStatus = null
+      adoptedAssets = [
+        {
+          assetId: ROOT_MANIFEST_ASSET_ID,
+          path: ROOT_MANIFEST_PATH,
+          adoptedFrom: "user-existing",
+          status: "adopted",
+        },
+      ]
+    }
+  }
+
+  const hasExistingInstallState = existingInstallState !== null
+
+  if (hasExistingInstallState) {
+    conflicts.push(
+      createMaterializationConflict({
+        assetId: INSTALL_STATE_ASSET_ID,
+        path: INSTALL_STATE_PATH,
+        reason: "existing-managed-asset",
+        resolution: "manual-review-required",
+      }),
+    )
+  }
+
+  if (hasExistingInstallState) {
+    return {
+      rootManifestPath,
+      installStatePath,
+      managedAssets: [],
+      adoptedAssets,
+      warnings,
+      conflicts,
+    }
+  }
+
+  if (conflicts.length > 0) {
+    return {
+      rootManifestPath,
+      installStatePath,
+      managedAssets: [],
+      adoptedAssets,
+      warnings,
+      conflicts,
+    }
+  }
+
+  const managedAssets = []
+
+  if (rootManifestManagedStatus !== null) {
+    managedAssets.push({
+      assetId: ROOT_MANIFEST_ASSET_ID,
+      path: ROOT_MANIFEST_PATH,
+      status: rootManifestManagedStatus,
+    })
+  }
+
+  managedAssets.push({
+    assetId: INSTALL_STATE_ASSET_ID,
+    path: INSTALL_STATE_PATH,
+    status: "managed",
+  })
+
+  const installState = createInstallState({
+    kitVersion,
+    profile: "openkit-core",
+    managedAssets,
+    adoptedAssets,
+    warnings,
+    conflicts,
+    now,
+  })
+
+  writeJson(installStatePath, installState)
+
+  try {
+    writeJson(rootManifestPath, rootManifestToWrite)
+  } catch (error) {
+    removeFileIfPresent(installStatePath)
+    throw error
+  }
+
+  return {
+    rootManifestPath,
+    installStatePath,
+    managedAssets,
+    adoptedAssets,
+    warnings,
+    conflicts,
+  }
+}

package/src/install/merge-policy.js

@@ -0,0 +1,145 @@
+const OPENKIT_MERGE_ALLOWLIST = new Set([
+  "plugin",
+  "instructions",
+  "installState",
+  "productSurface",
+])
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return [...value]
+  }
+
+  if (isPlainObject(value)) {
+    return { ...value }
+  }
+
+  return value
+}
+
+function mergeUniqueArray(currentValue, desiredValue) {
+  const currentItems = Array.isArray(currentValue) ? currentValue : []
+  const desiredItems = Array.isArray(desiredValue) ? desiredValue : []
+  const merged = [...currentItems]
+
+  for (const item of desiredItems) {
+    if (!merged.some((existing) => Object.is(existing, item))) {
+      merged.push(item)
+    }
+  }
+
+  return merged
+}
+
+function valuesMatch(currentValue, desiredValue) {
+  if (Object.is(currentValue, desiredValue)) {
+    return true
+  }
+
+  if (Array.isArray(currentValue) || Array.isArray(desiredValue)) {
+    if (!Array.isArray(currentValue) || !Array.isArray(desiredValue)) {
+      return false
+    }
+
+    if (currentValue.length !== desiredValue.length) {
+      return false
+    }
+
+    return currentValue.every((item, index) => valuesMatch(item, desiredValue[index]))
+  }
+
+  if (isPlainObject(currentValue) || isPlainObject(desiredValue)) {
+    if (!isPlainObject(currentValue) || !isPlainObject(desiredValue)) {
+      return false
+    }
+
+    const currentKeys = Object.keys(currentValue).sort()
+    const desiredKeys = Object.keys(desiredValue).sort()
+
+    if (!valuesMatch(currentKeys, desiredKeys)) {
+      return false
+    }
+
+    return currentKeys.every((key) => valuesMatch(currentValue[key], desiredValue[key]))
+  }
+
+  return false
+}
+
+export function applyOpenKitMergePolicy({ currentConfig = {}, desiredConfig = {} }) {
+  const config = {}
+  const conflicts = []
+  const appliedFields = []
+  const keys = new Set([...Object.keys(currentConfig), ...Object.keys(desiredConfig)])
+
+  for (const key of keys) {
+    const hasCurrent = Object.hasOwn(currentConfig, key)
+    const hasDesired = Object.hasOwn(desiredConfig, key)
+
+    if (!hasDesired) {
+      config[key] = cloneValue(currentConfig[key])
+      continue
+    }
+
+    if (OPENKIT_MERGE_ALLOWLIST.has(key)) {
+      if (Array.isArray(desiredConfig[key])) {
+        config[key] = mergeUniqueArray(currentConfig[key], desiredConfig[key])
+        appliedFields.push(key)
+        continue
+      }
+
+      if (!hasCurrent) {
+        config[key] = cloneValue(desiredConfig[key])
+        appliedFields.push(key)
+        continue
+      }
+
+      config[key] = cloneValue(currentConfig[key])
+
+      if (!valuesMatch(currentConfig[key], desiredConfig[key])) {
+        conflicts.push({
+          field: key,
+          reason: "unsupported-top-level-key",
+          currentValue: cloneValue(currentConfig[key]),
+          desiredValue: cloneValue(desiredConfig[key]),
+        })
+      } else {
+        appliedFields.push(key)
+      }
+
+      continue
+    }
+
+    if (!hasCurrent) {
+      conflicts.push({
+        field: key,
+        reason: "unclassified-top-level-key",
+        currentValue: undefined,
+        desiredValue: cloneValue(desiredConfig[key]),
+      })
+      continue
+    }
+
+    config[key] = cloneValue(currentConfig[key])
+
+    if (!Object.is(currentConfig[key], desiredConfig[key])) {
+      conflicts.push({
+        field: key,
+        reason: "unsupported-top-level-key",
+        currentValue: cloneValue(currentConfig[key]),
+        desiredValue: cloneValue(desiredConfig[key]),
+      })
+    }
+  }
+
+  return {
+    config,
+    conflicts,
+    appliedFields,
+    mergeAllowlist: [...OPENKIT_MERGE_ALLOWLIST],
+  }
+}

package/src/runtime/doctor.js

@@ -0,0 +1,281 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { validateInstallState } from '../install/install-state.js';
+import { discoverProjectShape } from '../install/discovery.js';
+
+const EXPECTED_MANAGED_ASSETS = {
+  'runtime.opencode-manifest': {
+    path: 'opencode.json',
+    validate(contents) {
+      return (
+        contents?.installState?.path === '.openkit/openkit-install.json' &&
+        contents?.installState?.schema === 'openkit/install-state@1' &&
+        contents?.productSurface?.current === 'global-openkit-install' &&
+        contents?.productSurface?.installReadiness === 'managed' &&
+        contents?.productSurface?.installationMode === 'openkit-managed'
+      );
+    },
+  },
+  'runtime.install-state': {
+    path: '.openkit/openkit-install.json',
+    validate(contents) {
+      return contents?.installation?.profile === 'openkit-core';
+    },
+  },
+};
+
+const ROOT_MANIFEST_ASSET_ID = 'runtime.opencode-manifest';
+
+function readJsonIfPresent(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {
+      exists: false,
+      malformed: false,
+      value: null,
+    };
+  }
+
+  try {
+    return {
+      exists: true,
+      malformed: false,
+      value: JSON.parse(fs.readFileSync(filePath, 'utf8')),
+    };
+  } catch {
+    return {
+      exists: true,
+      malformed: true,
+      value: null,
+    };
+  }
+}
+
+function defaultIsOpenCodeAvailable() {
+  const pathValue = process.env.PATH ?? '';
+  return pathValue.split(path.delimiter).some((segment) => {
+    if (!segment) {
+      return false;
+    }
+
+    const candidate = path.join(segment, 'opencode');
+    return fs.existsSync(candidate);
+  });
+}
+
+export function inspectManagedDoctor({
+  projectRoot,
+  env = process.env,
+  isOpenCodeAvailable = defaultIsOpenCodeAvailable,
+} = {}) {
+  const resolvedProjectRoot = projectRoot ?? process.cwd();
+  const rootManifestPath = path.join(resolvedProjectRoot, 'opencode.json');
+  const runtimeManifestPath = path.join(resolvedProjectRoot, '.opencode', 'opencode.json');
+  const installStatePath = path.join(resolvedProjectRoot, '.openkit', 'openkit-install.json');
+  const rootManifestResult = readJsonIfPresent(rootManifestPath);
+  const installStateResult = readJsonIfPresent(installStatePath);
+  const rootManifest = rootManifestResult.value;
+  const installState = installStateResult.value;
+  const issues = [];
+  const driftedAssets = [];
+  const ownedAssets = {
+    managed: [],
+    adopted: [],
+  };
+  const classification = discoverProjectShape(resolvedProjectRoot).classification;
+
+  if (!rootManifestResult.exists && !installStateResult.exists) {
+    return {
+      status: 'install-missing',
+      canRunCleanly: false,
+      summary: 'Managed install was not found; openkit run cannot proceed cleanly.',
+      issues: ['Managed install entrypoint was not found at opencode.json.'],
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  if (!rootManifestResult.exists || !installStateResult.exists) {
+    if (installState) {
+      const installStateErrors = validateInstallState(installState);
+      if (installStateErrors.length === 0) {
+        ownedAssets.managed = (installState.assets?.managed ?? []).map((asset) => asset.path);
+        ownedAssets.adopted = (installState.assets?.adopted ?? []).map((asset) => asset.path);
+      }
+    }
+
+    const missingAssets = [];
+    if (!rootManifestResult.exists) {
+      missingAssets.push('Missing required managed asset: opencode.json');
+    }
+    if (!installStateResult.exists) {
+      missingAssets.push('Missing required managed asset: .openkit/openkit-install.json');
+    }
+
+    return {
+      status: 'install-incomplete',
+      canRunCleanly: false,
+      summary: 'Managed install is incomplete; openkit run cannot proceed cleanly.',
+      issues: missingAssets,
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  if (rootManifestResult.malformed || installStateResult.malformed) {
+    if (installState && !installStateResult.malformed) {
+      const installStateErrors = validateInstallState(installState);
+      if (installStateErrors.length === 0) {
+        ownedAssets.managed = (installState.assets?.managed ?? []).map((asset) => asset.path);
+        ownedAssets.adopted = (installState.assets?.adopted ?? []).map((asset) => asset.path);
+      }
+    }
+
+    if (rootManifestResult.malformed) {
+      driftedAssets.push('opencode.json');
+      issues.push('Managed asset JSON is malformed: opencode.json');
+    }
+
+    if (installStateResult.malformed) {
+      driftedAssets.push('.openkit/openkit-install.json');
+      issues.push('Managed asset JSON is malformed: .openkit/openkit-install.json');
+    }
+
+    return {
+      status: 'drift-detected',
+      canRunCleanly: false,
+      summary: 'Managed asset drift was detected; review managed install files before running OpenKit.',
+      issues,
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  const installStateErrors = validateInstallState(installState);
+  if (installStateErrors.length > 0) {
+    return {
+      status: 'install-incomplete',
+      canRunCleanly: false,
+      summary: 'Managed install is incomplete; install state is invalid.',
+      issues: installStateErrors,
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  ownedAssets.managed = (installState.assets?.managed ?? []).map((asset) => asset.path);
+  ownedAssets.adopted = (installState.assets?.adopted ?? []).map((asset) => asset.path);
+
+  const adoptedRootManifest = (installState.assets?.adopted ?? []).some(
+    (asset) => asset?.assetId === ROOT_MANIFEST_ASSET_ID && asset?.path === 'opencode.json'
+  );
+
+  if (adoptedRootManifest && !EXPECTED_MANAGED_ASSETS[ROOT_MANIFEST_ASSET_ID].validate(rootManifest)) {
+    return {
+      status: 'install-incomplete',
+      canRunCleanly: false,
+      summary: 'Managed install contract is incomplete; adopted root manifest is not compatible enough to run cleanly.',
+      issues: ['Adopted root manifest is incompatible with the managed install contract.'],
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  for (const asset of installState.assets?.managed ?? []) {
+    const expectedAsset = EXPECTED_MANAGED_ASSETS[asset.assetId];
+
+    if (!expectedAsset) {
+      continue;
+    }
+
+    const assetPath = path.join(resolvedProjectRoot, asset.path);
+    const contentsResult = readJsonIfPresent(assetPath);
+    const contents = contentsResult.value;
+
+    if (contentsResult.malformed) {
+      if (!driftedAssets.includes(asset.path)) {
+        driftedAssets.push(asset.path);
+      }
+      issues.push(`Managed asset JSON is malformed: ${asset.path}`);
+      continue;
+    }
+
+    if (!contentsResult.exists || !expectedAsset.validate(contents)) {
+      if (!driftedAssets.includes(asset.path)) {
+        driftedAssets.push(asset.path);
+      }
+      issues.push(`Drift detected for managed asset: ${asset.path}`);
+    }
+  }
+
+  if (driftedAssets.length > 0) {
+    return {
+      status: 'drift-detected',
+      canRunCleanly: false,
+      summary: 'Managed asset drift was detected; review managed install files before running OpenKit.',
+      issues,
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  if (!fs.existsSync(runtimeManifestPath)) {
+    issues.push('Missing runtime manifest: .opencode/opencode.json');
+  }
+
+  if (!isOpenCodeAvailable(env)) {
+    issues.push('OpenCode executable is not available on PATH');
+  }
+
+  if (issues.length > 0) {
+    return {
+      status: 'runtime-prerequisites-missing',
+      canRunCleanly: false,
+      summary: 'Runtime launch prerequisites are missing; openkit run cannot proceed cleanly.',
+      issues,
+      driftedAssets,
+      ownedAssets,
+      classification,
+      rootManifestPath,
+      runtimeManifestPath,
+      installStatePath,
+    };
+  }
+
+  return {
+    status: 'healthy',
+    canRunCleanly: true,
+    summary: 'Managed install is healthy; openkit run can proceed cleanly.',
+    issues: [],
+    driftedAssets,
+    ownedAssets,
+    classification,
+    rootManifestPath,
+    runtimeManifestPath,
+    installStatePath,
+  };
+}

package/src/runtime/launcher.js

@@ -0,0 +1,49 @@
+import { spawnSync } from 'node:child_process';
+
+import { buildOpenCodeLayering } from './opencode-layering.js';
+
+function formatMissingOpenCodeError() {
+  return [
+    'Could not find `opencode` on your PATH.',
+    'The supported launcher path is `openkit run`, which applies managed config layering for this session.',
+    'Install OpenCode or add `opencode` to PATH, then retry.',
+  ].join('\n');
+}
+
+export function launchManagedOpenCode(
+  args = [],
+  {
+    projectRoot = process.cwd(),
+    env = process.env,
+    spawn = spawnSync,
+    stdio = 'inherit',
+  } = {}
+) {
+  const layering = buildOpenCodeLayering({ projectRoot, env });
+  const result = spawn('opencode', args, {
+    cwd: projectRoot,
+    env: layering.env,
+    encoding: 'utf8',
+    stdio,
+  });
+
+  if (result.error?.code === 'ENOENT') {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: `${formatMissingOpenCodeError()}\n`,
+      layering,
+    };
+  }
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return {
+    exitCode: typeof result.status === 'number' ? result.status : 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    layering,
+  };
+}