@duypham93/openkit 0.2.0

package/src/runtime/opencode-layering.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const CONFIG_DIR_RELATIVE_PATHS = [
+  'agents_dir',
+  'commands_dir',
+  'skills_dir',
+  'hooks.config',
+];
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function deepMerge(base, overlay) {
+  if (!isPlainObject(base) || !isPlainObject(overlay)) {
+    return overlay;
+  }
+
+  const result = { ...base };
+
+  for (const [key, value] of Object.entries(overlay)) {
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value);
+      continue;
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+function readJsonIfPresent(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function parseJsonContent(content, sourceLabel) {
+  if (!content) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`${sourceLabel} must contain valid JSON.`, { cause: error });
+  }
+}
+
+function shouldResolveRelativeToConfigDir(keyPath) {
+  const joinedPath = keyPath.filter((segment) => typeof segment === 'string').join('.');
+  return CONFIG_DIR_RELATIVE_PATHS.includes(joinedPath);
+}
+
+function normalizeConfigPaths(value, configDir, keyPath = []) {
+  if (Array.isArray(value)) {
+    return value.map((entry, index) => normalizeConfigPaths(entry, configDir, [...keyPath, index]));
+  }
+
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        normalizeConfigPaths(entry, configDir, [...keyPath, key]),
+      ])
+    );
+  }
+
+  if (typeof value !== 'string' || !configDir || path.isAbsolute(value)) {
+    return value;
+  }
+
+  if (!shouldResolveRelativeToConfigDir(keyPath)) {
+    return value;
+  }
+
+  return path.resolve(configDir, value);
+}
+
+export function buildOpenCodeLayering({ projectRoot, env = process.env }) {
+  const runtimeManifestPath = path.join(projectRoot, '.opencode', 'opencode.json');
+  const managedConfigDir = path.dirname(runtimeManifestPath);
+  const managedConfig = readJsonIfPresent(runtimeManifestPath);
+
+  if (!managedConfig) {
+    throw new Error(
+      `OpenKit managed runtime manifest was not found at ${runtimeManifestPath}.`
+    );
+  }
+
+  const baselineConfigDir = env.OPENCODE_CONFIG_DIR ?? null;
+  const baselineDirConfig = baselineConfigDir
+    ? readJsonIfPresent(path.join(baselineConfigDir, 'opencode.json'))
+    : null;
+  const baselineContentConfig = parseJsonContent(
+    env.OPENCODE_CONFIG_CONTENT,
+    'OPENCODE_CONFIG_CONTENT'
+  );
+
+  const normalizedBaselineDirConfig = normalizeConfigPaths(baselineDirConfig ?? {}, baselineConfigDir);
+  const normalizedBaselineContentConfig = normalizeConfigPaths(
+    baselineContentConfig ?? {},
+    baselineConfigDir
+  );
+  const baselineConfig = deepMerge(normalizedBaselineDirConfig, normalizedBaselineContentConfig);
+  const mergedConfig = deepMerge(baselineConfig, managedConfig);
+  const layeredEnv = { ...env };
+
+  if (baselineConfigDir || baselineContentConfig) {
+    layeredEnv.OPENCODE_CONFIG_DIR = managedConfigDir;
+    layeredEnv.OPENCODE_CONFIG_CONTENT = JSON.stringify(mergedConfig);
+  } else {
+    layeredEnv.OPENCODE_CONFIG_DIR = managedConfigDir;
+    delete layeredEnv.OPENCODE_CONFIG_CONTENT;
+  }
+
+  return {
+    env: layeredEnv,
+    baseline: {
+      configDir: baselineConfigDir,
+      hasConfigContent: Boolean(baselineContentConfig),
+      config: baselineConfig,
+    },
+    managedConfig: {
+      configDir: managedConfigDir,
+      runtimeManifestPath,
+      config: managedConfig,
+    },
+    mergedConfig,
+  };
+}

package/src/runtime/openkit-managed-summary.js

@@ -0,0 +1,27 @@
+function formatList(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    return 'none';
+  }
+
+  return values.join(', ');
+}
+
+export function renderManagedDoctorSummary(result) {
+  const lines = [
+    `Status: ${result.status}`,
+    `Summary: ${result.summary}`,
+    `Can run cleanly: ${result.canRunCleanly ? 'yes' : 'no'}`,
+    `Owned by OpenKit: ${formatList(result.ownedAssets?.managed)}`,
+    `Adopted by OpenKit: ${formatList(result.ownedAssets?.adopted)}`,
+    `Drifted assets: ${formatList(result.driftedAssets)}`,
+  ];
+
+  if (Array.isArray(result.issues) && result.issues.length > 0) {
+    lines.push('Issues:');
+    for (const issue of result.issues) {
+      lines.push(`- ${issue}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/tests/cli/openkit-cli.test.js

@@ -0,0 +1,417 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const worktreeRoot = path.resolve(__dirname, '..', '..');
+const binPath = path.join(worktreeRoot, 'bin', 'openkit.js');
+
+function runCli(args, { cwd = worktreeRoot, env } = {}) {
+  return spawnSync(process.execPath, [binPath, ...args], {
+    cwd,
+    encoding: 'utf8',
+    env: env ?? process.env,
+  });
+}
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'openkit-cli-'));
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeExecutable(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  fs.chmodSync(filePath, 0o755);
+}
+
+test('openkit --help shows global-install oriented help', () => {
+  const result = runCli(['--help']);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /npm install -g openkit/);
+  assert.match(result.stdout, /perform first-time setup if needed/);
+  assert.match(result.stdout, /install-global/);
+  assert.match(result.stdout, /upgrade/);
+  assert.match(result.stdout, /uninstall/);
+  assert.match(result.stdout, /Launch OpenCode and perform first-time setup if needed/);
+  assert.equal(result.stderr, '');
+});
+
+test('openkit doctor --help shows global doctor help', () => {
+  const result = runCli(['doctor', '--help']);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /global OpenKit install and the current workspace/);
+  assert.equal(result.stderr, '');
+});
+
+test('install command help reflects manual and compatibility setup paths', () => {
+  const installGlobalResult = runCli(['install-global', '--help']);
+  const installResult = runCli(['install', '--help']);
+  const initResult = runCli(['init', '--help']);
+
+  assert.equal(installGlobalResult.status, 0);
+  assert.match(installGlobalResult.stdout, /Manually install OpenKit globally/i);
+  assert.match(installGlobalResult.stdout, /Most users should run `openkit run`/i);
+
+  assert.equal(installResult.status, 0);
+  assert.match(installResult.stdout, /Compatibility alias for manual global setup/i);
+  assert.match(installResult.stdout, /Most users should run `openkit run`/i);
+
+  assert.equal(initResult.status, 0);
+  assert.match(initResult.stdout, /Compatibility alias for manual global setup/i);
+  assert.match(initResult.stdout, /Most users should run `openkit run`/i);
+});
+
+test('openkit install-global materializes global kit and profile files', () => {
+  const tempHome = makeTempDir();
+  const result = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Installed OpenKit globally/);
+
+  const kitRoot = path.join(tempHome, 'kits', 'openkit');
+  const profileRoot = path.join(tempHome, 'profiles', 'openkit');
+
+  assert.equal(fs.existsSync(path.join(kitRoot, '.opencode', 'workflow-state.js')), true);
+  assert.equal(fs.existsSync(path.join(kitRoot, 'commands', 'migrate.md')), true);
+  assert.equal(fs.existsSync(path.join(profileRoot, 'opencode.json')), true);
+  assert.equal(readJson(path.join(profileRoot, 'opencode.json')).openkit.profile, 'openkit');
+});
+
+test('openkit init and install remain compatibility aliases for install-global', () => {
+  const tempHome = makeTempDir();
+
+  const initResult = runCli(['init'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  const installResult = runCli(['install'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+
+  assert.equal(initResult.status, 0);
+  assert.equal(installResult.status, 0);
+  assert.match(initResult.stdout, /Installed OpenKit globally/);
+  assert.match(installResult.stdout, /Installed OpenKit globally/);
+});
+
+test('openkit doctor reports install-missing when global install is absent', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+
+  const result = runCli(['doctor'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: '',
+    },
+  });
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /Status: install-missing/);
+  assert.match(result.stdout, /Global OpenKit install was not found/);
+  assert.match(result.stdout, /Next: Run openkit run for first-time setup/);
+  assert.match(result.stdout, /Recommended command: openkit run/);
+});
+
+test('openkit doctor reports healthy after global install and bootstraps workspace metadata', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+  writeExecutable(path.join(fakeBinDir, 'opencode'), '#!/bin/sh\nexit 0\n');
+
+  const installResult = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(installResult.status, 0);
+
+  const result = runCli(['doctor'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Status: healthy/);
+  assert.match(result.stdout, /Workspace root:/);
+  assert.match(result.stdout, /Next: Run openkit run/);
+  assert.match(result.stdout, /Recommended command: openkit run/);
+
+  const workspacesRoot = path.join(tempHome, 'workspaces');
+  const workspaceEntries = fs.readdirSync(workspacesRoot);
+  assert.equal(workspaceEntries.length, 1);
+  const workspaceMetaPath = path.join(workspacesRoot, workspaceEntries[0], 'openkit', 'workspace.json');
+  assert.equal(fs.existsSync(workspaceMetaPath), true);
+});
+
+test('openkit run launches opencode with the global profile and workspace env', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+  const logPath = path.join(tempHome, 'opencode-run.json');
+
+  const installResult = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(installResult.status, 0);
+
+  writeExecutable(
+    path.join(fakeBinDir, 'opencode'),
+    `#!/usr/bin/env node
+import fs from 'node:fs';
+fs.writeFileSync(process.env.OPENKIT_TEST_LOG_PATH, JSON.stringify({
+  argv: process.argv.slice(2),
+  cwd: process.cwd(),
+  projectRoot: process.env.OPENKIT_PROJECT_ROOT,
+  workflowState: process.env.OPENKIT_WORKFLOW_STATE,
+  kitRoot: process.env.OPENKIT_KIT_ROOT,
+  configDir: process.env.OPENCODE_CONFIG_DIR,
+}, null, 2));
+process.stdout.write('mock opencode launched\\n');
+`
+  );
+
+  const result = runCli(['run', '--mode', 'quick'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      OPENKIT_TEST_LOG_PATH: logPath,
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /mock opencode launched/);
+
+  const invocation = readJson(logPath);
+  assert.deepEqual(invocation.argv, ['--profile', 'openkit', '--mode', 'quick']);
+  assert.equal(fs.realpathSync(invocation.cwd), fs.realpathSync(projectRoot));
+  assert.equal(fs.realpathSync(invocation.projectRoot), fs.realpathSync(projectRoot));
+  assert.equal(invocation.configDir, path.join(tempHome, 'profiles', 'openkit'));
+  assert.match(invocation.workflowState, /workspaces\/.*\/openkit\/\.opencode\/workflow-state\.json$/);
+  assert.equal(invocation.kitRoot, path.join(tempHome, 'kits', 'openkit'));
+});
+
+test('openkit run does not reinstall when the global install already exists', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+
+  const installResult = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(installResult.status, 0);
+
+  writeExecutable(path.join(fakeBinDir, 'opencode'), '#!/bin/sh\necho already-installed-run\n');
+
+  const result = runCli(['run'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+
+  assert.equal(result.status, 0);
+  assert.doesNotMatch(result.stdout, /Performing first-time setup/);
+  assert.match(result.stdout, /already-installed-run/);
+});
+
+test('openkit run auto-installs the global kit on first use', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+  const logPath = path.join(tempHome, 'opencode-auto-install.json');
+
+  writeExecutable(
+    path.join(fakeBinDir, 'opencode'),
+    `#!/usr/bin/env node
+import fs from 'node:fs';
+fs.writeFileSync(process.env.OPENKIT_TEST_LOG_PATH, JSON.stringify({
+  argv: process.argv.slice(2),
+  cwd: process.cwd(),
+  projectRoot: process.env.OPENKIT_PROJECT_ROOT,
+  workflowState: process.env.OPENKIT_WORKFLOW_STATE,
+  kitRoot: process.env.OPENKIT_KIT_ROOT,
+  configDir: process.env.OPENCODE_CONFIG_DIR,
+}, null, 2));
+process.stdout.write('mock opencode launched after auto-install\\n');
+`
+  );
+
+  const result = runCli(['run'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      OPENKIT_TEST_LOG_PATH: logPath,
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Performing first-time setup/);
+  assert.match(result.stdout, /Installed OpenKit globally/);
+  assert.match(result.stdout, /mock opencode launched after auto-install/);
+  assert.equal(fs.existsSync(path.join(tempHome, 'kits', 'openkit', '.opencode', 'workflow-state.js')), true);
+
+  const invocation = readJson(logPath);
+  assert.deepEqual(invocation.argv, ['--profile', 'openkit']);
+  assert.equal(invocation.kitRoot, path.join(tempHome, 'kits', 'openkit'));
+});
+
+test('openkit run reports missing opencode after first-time setup completes', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+
+  const result = runCli(['run'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: '',
+    },
+  });
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /Performing first-time setup/);
+  assert.match(result.stdout, /Installed OpenKit globally/);
+  assert.match(result.stderr, /Could not find `opencode` on your PATH/);
+});
+
+test('openkit run blocks on invalid global install state and recommends upgrade', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const kitRoot = path.join(tempHome, 'kits', 'openkit');
+
+  fs.mkdirSync(kitRoot, { recursive: true });
+  fs.writeFileSync(
+    path.join(kitRoot, 'install-state.json'),
+    `${JSON.stringify({
+      schema: 'wrong-schema',
+      stateVersion: 1,
+      kit: { name: 'OpenKit', version: '0.1.0' },
+      installation: {
+        profile: 'openkit',
+        status: 'installed',
+        installedAt: '2026-03-24T00:00:00.000Z',
+      },
+    }, null, 2)}\n`,
+    'utf8'
+  );
+
+  const result = runCli(['run'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: process.env.PATH ?? '',
+    },
+  });
+
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /schema must be 'openkit\/global-install-state@1'/i);
+  assert.match(result.stderr, /Next: Run openkit upgrade to refresh the global install/i);
+});
+
+test('openkit upgrade refreshes the global kit install', () => {
+  const tempHome = makeTempDir();
+
+  const installResult = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(installResult.status, 0);
+
+  const result = runCli(['upgrade'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Upgraded OpenKit global install/);
+});
+
+test('openkit uninstall removes the global kit and profile and can remove workspace state', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+  writeExecutable(path.join(fakeBinDir, 'opencode'), '#!/bin/sh\nexit 0\n');
+
+  let result = runCli(['install-global'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(result.status, 0);
+
+  result = runCli(['doctor'], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH}`,
+    },
+  });
+  assert.equal(result.status, 0);
+
+  result = runCli(['uninstall', '--remove-workspaces'], {
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Uninstalled OpenKit global kit/);
+  assert.match(result.stdout, /Workspace state was removed/);
+  assert.equal(fs.existsSync(path.join(tempHome, 'kits', 'openkit')), false);
+  assert.equal(fs.existsSync(path.join(tempHome, 'profiles', 'openkit')), false);
+  assert.equal(fs.existsSync(path.join(tempHome, 'workspaces')), false);
+});
+
+test('openkit exits non-zero for an unknown command', () => {
+  const result = runCli(['unknown-command']);
+
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /Unknown command: unknown-command/);
+});

package/tests/global/doctor.test.js

@@ -0,0 +1,130 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { inspectGlobalDoctor, renderGlobalDoctorSummary } from '../../src/global/doctor.js';
+import { materializeGlobalInstall } from '../../src/global/materialize.js';
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'openkit-global-doctor-'));
+}
+
+function writeExecutable(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  fs.chmodSync(filePath, 0o755);
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+test('global doctor reports next steps for install-missing', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+
+  const result = inspectGlobalDoctor({
+    projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: '',
+    },
+  });
+
+  assert.equal(result.status, 'install-missing');
+  assert.equal(result.nextStep, 'Run openkit run for first-time setup.');
+  assert.equal(result.recommendedCommand, 'openkit run');
+
+  const output = renderGlobalDoctorSummary(result);
+  assert.match(output, /Next: Run openkit run for first-time setup\./);
+  assert.match(output, /Recommended command: openkit run/);
+});
+
+test('global doctor reports next steps for healthy installs', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+
+  materializeGlobalInstall({
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+  writeExecutable(path.join(fakeBinDir, 'opencode'), '#!/bin/sh\nexit 0\n');
+
+  const result = inspectGlobalDoctor({
+    projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH ?? ''}`,
+    },
+  });
+
+  assert.equal(result.status, 'healthy');
+  assert.equal(result.nextStep, 'Run openkit run.');
+  assert.equal(result.recommendedCommand, 'openkit run');
+});
+
+test('global doctor recommends upgrade for invalid installs', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(tempHome, 'kits', 'openkit', 'install-state.json'), {
+    schema: 'wrong-schema',
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: '0.1.0',
+    },
+    installation: {
+      profile: 'openkit',
+      status: 'installed',
+      installedAt: '2026-03-24T00:00:00.000Z',
+    },
+  });
+
+  const result = inspectGlobalDoctor({
+    projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: process.env.PATH ?? '',
+    },
+  });
+
+  assert.equal(result.status, 'install-invalid');
+  assert.equal(result.nextStep, 'Run openkit upgrade to refresh the global install.');
+  assert.equal(result.recommendedCommand, 'openkit upgrade');
+});
+
+test('global doctor reports workspace issues with guidance', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+
+  materializeGlobalInstall({
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+    },
+  });
+
+  const result = inspectGlobalDoctor({
+    projectRoot,
+    env: {
+      ...process.env,
+      OPENCODE_HOME: tempHome,
+      PATH: '',
+    },
+  });
+
+  assert.equal(result.status, 'workspace-ready-with-issues');
+  assert.equal(result.nextStep, 'Review the issues above before relying on this workspace.');
+  assert.equal(result.recommendedCommand, null);
+  assert.match(result.issues.join('\n'), /OpenCode executable is not available on PATH/);
+});