@duypham93/openkit 0.2.0

package/tests/runtime/doctor.test.js

@@ -0,0 +1,430 @@
+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 { inspectManagedDoctor } from '../../src/runtime/doctor.js';
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'openkit-doctor-'));
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function writeText(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, value, 'utf8');
+}
+
+function materializeManagedInstall(projectRoot) {
+  writeJson(path.join(projectRoot, 'opencode.json'), {
+    installState: {
+      path: '.openkit/openkit-install.json',
+      schema: 'openkit/install-state@1',
+    },
+    productSurface: {
+      current: 'global-openkit-install',
+      installReadiness: 'managed',
+      installationMode: 'openkit-managed',
+    },
+  });
+
+  writeJson(path.join(projectRoot, '.openkit', 'openkit-install.json'), {
+    schema: 'openkit/install-state@1',
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: '0.1.0',
+    },
+    installation: {
+      profile: 'openkit-core',
+      status: 'installed',
+      installedAt: '2026-03-22T12:00:00.000Z',
+    },
+    assets: {
+      managed: [
+        { assetId: 'runtime.opencode-manifest', path: 'opencode.json', status: 'materialized' },
+        { assetId: 'runtime.install-state', path: '.openkit/openkit-install.json', status: 'managed' },
+      ],
+      adopted: [],
+    },
+    warnings: [],
+    conflicts: [],
+  });
+}
+
+test('doctor reports install missing when managed install files are absent', () => {
+  const projectRoot = makeTempDir();
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => false,
+  });
+
+  assert.equal(result.status, 'install-missing');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.ownedAssets.managed, []);
+  assert.match(result.summary, /managed install was not found/i);
+  assert.match(result.summary, /openkit run cannot proceed cleanly/i);
+});
+
+test('doctor reports install incomplete when install state is missing', () => {
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(projectRoot, 'opencode.json'), {
+    installState: {
+      path: '.openkit/openkit-install.json',
+      schema: 'openkit/install-state@1',
+    },
+    productSurface: {
+      current: 'global-openkit-install',
+      installReadiness: 'managed',
+      installationMode: 'openkit-managed',
+    },
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'install-incomplete');
+  assert.equal(result.canRunCleanly, false);
+  assert.match(result.summary, /install is incomplete/i);
+  assert.deepEqual(result.issues, [
+    'Missing required managed asset: .openkit/openkit-install.json',
+  ]);
+});
+
+test('doctor reports install incomplete for a partial install when install state exists but install entrypoint is missing', () => {
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(projectRoot, '.openkit', 'openkit-install.json'), {
+    schema: 'openkit/install-state@1',
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: '0.1.0',
+    },
+    installation: {
+      profile: 'openkit-core',
+      status: 'installed',
+      installedAt: '2026-03-22T12:00:00.000Z',
+    },
+    assets: {
+      managed: [
+        { assetId: 'runtime.opencode-manifest', path: 'opencode.json', status: 'materialized' },
+        { assetId: 'runtime.install-state', path: '.openkit/openkit-install.json', status: 'managed' },
+      ],
+      adopted: [],
+    },
+    warnings: [],
+    conflicts: [],
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'install-incomplete');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.ownedAssets.managed, ['opencode.json', '.openkit/openkit-install.json']);
+  assert.match(result.summary, /install is incomplete/i);
+  assert.match(result.issues.join('\n'), /Missing required managed asset: opencode\.json/);
+});
+
+test('doctor reports drift when a managed asset changed on disk', () => {
+  const projectRoot = makeTempDir();
+
+  materializeManagedInstall(projectRoot);
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  writeJson(path.join(projectRoot, 'opencode.json'), {
+    installState: {
+      path: '.openkit/openkit-install.json',
+      schema: 'openkit/install-state@1',
+    },
+    productSurface: {
+      current: 'changed-wrapper-surface',
+      installReadiness: 'managed',
+      installationMode: 'openkit-managed',
+    },
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'drift-detected');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.driftedAssets, ['opencode.json']);
+  assert.match(result.summary, /managed asset drift was detected/i);
+  assert.match(result.issues[0], /Drift detected for managed asset: opencode\.json/);
+});
+
+test('doctor reports drift for managed install-state assets it owns in phase 1', () => {
+  const projectRoot = makeTempDir();
+
+  materializeManagedInstall(projectRoot);
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  writeJson(path.join(projectRoot, '.openkit', 'openkit-install.json'), {
+    schema: 'openkit/install-state@1',
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: '0.1.0',
+    },
+    installation: {
+      profile: 'custom-profile',
+      status: 'installed',
+      installedAt: '2026-03-22T12:00:00.000Z',
+    },
+    assets: {
+      managed: [
+        { assetId: 'runtime.opencode-manifest', path: 'opencode.json', status: 'materialized' },
+        { assetId: 'runtime.install-state', path: '.openkit/openkit-install.json', status: 'managed' },
+      ],
+      adopted: [],
+    },
+    warnings: [],
+    conflicts: [],
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'drift-detected');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.driftedAssets, ['.openkit/openkit-install.json']);
+  assert.match(result.summary, /managed asset drift was detected/i);
+  assert.match(
+    result.issues.join('\n'),
+    /Drift detected for managed asset: \.openkit\/openkit-install\.json/
+  );
+});
+
+test('doctor reports malformed install manifest JSON as diagnosable drift instead of crashing', () => {
+  const projectRoot = makeTempDir();
+
+  materializeManagedInstall(projectRoot);
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+  writeText(path.join(projectRoot, 'opencode.json'), '{"installState": ');
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'drift-detected');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.driftedAssets, ['opencode.json']);
+  assert.match(result.issues.join('\n'), /Managed asset JSON is malformed: opencode\.json/);
+});
+
+test('doctor reports malformed managed install-state JSON as diagnosable drift instead of crashing', () => {
+  const projectRoot = makeTempDir();
+
+  materializeManagedInstall(projectRoot);
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+  writeText(path.join(projectRoot, '.openkit', 'openkit-install.json'), '{"schema": ');
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'drift-detected');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.driftedAssets, ['.openkit/openkit-install.json']);
+  assert.match(
+    result.issues.join('\n'),
+    /Managed asset JSON is malformed: \.openkit\/openkit-install\.json/
+  );
+});
+
+test('doctor reports runtime prerequisites missing when install is intact but launcher prerequisites are absent', () => {
+  const projectRoot = makeTempDir();
+
+  materializeManagedInstall(projectRoot);
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => false,
+  });
+
+  assert.equal(result.status, 'runtime-prerequisites-missing');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.driftedAssets, []);
+  assert.deepEqual(result.ownedAssets.managed, ['opencode.json', '.openkit/openkit-install.json']);
+  assert.match(result.summary, /runtime launch prerequisites are missing/i);
+  assert.match(result.issues.join('\n'), /Missing runtime manifest: \.opencode\/opencode\.json/);
+  assert.match(result.issues.join('\n'), /OpenCode executable is not available on PATH/);
+});
+
+test('doctor reports healthy state when install is intact and launcher prerequisites are available', () => {
+  const projectRoot = makeTempDir();
+
+  materializeManagedInstall(projectRoot);
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'healthy');
+  assert.equal(result.canRunCleanly, true);
+  assert.deepEqual(result.issues, []);
+  assert.deepEqual(result.driftedAssets, []);
+  assert.deepEqual(result.ownedAssets.managed, ['opencode.json', '.openkit/openkit-install.json']);
+  assert.match(result.summary, /managed install is healthy/i);
+  assert.match(result.summary, /openkit run can proceed cleanly/i);
+});
+
+test('doctor does not report healthy when an adopted root manifest is incompatible with the install contract', () => {
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(projectRoot, 'opencode.json'), {
+    plugin: ['existing-plugin'],
+    productSurface: {
+      current: 'custom-surface',
+    },
+  });
+  writeJson(path.join(projectRoot, '.openkit', 'openkit-install.json'), {
+    schema: 'openkit/install-state@1',
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: '0.1.0',
+    },
+    installation: {
+      profile: 'openkit-core',
+      status: 'installed',
+      installedAt: '2026-03-22T12:00:00.000Z',
+    },
+    assets: {
+      managed: [
+        { assetId: 'runtime.install-state', path: '.openkit/openkit-install.json', status: 'managed' },
+      ],
+      adopted: [
+        {
+          assetId: 'runtime.opencode-manifest',
+          path: 'opencode.json',
+          adoptedFrom: 'user-existing',
+          status: 'adopted',
+        },
+      ],
+    },
+    warnings: [],
+    conflicts: [
+      {
+        assetId: 'runtime.opencode-manifest',
+        path: 'opencode.json',
+        reason: 'unsupported-top-level-key',
+        resolution: 'manual-review-required',
+      },
+    ],
+  });
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'install-incomplete');
+  assert.equal(result.canRunCleanly, false);
+  assert.deepEqual(result.ownedAssets.adopted, ['opencode.json']);
+  assert.match(result.summary, /install contract is incomplete/i);
+  assert.match(result.issues.join('\n'), /adopted root manifest is incompatible with the managed install contract/i);
+});
+
+test('doctor can report healthy when an adopted root manifest still satisfies the install contract', () => {
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(projectRoot, 'opencode.json'), {
+    plugin: ['existing-plugin'],
+    installState: {
+      path: '.openkit/openkit-install.json',
+      schema: 'openkit/install-state@1',
+    },
+    productSurface: {
+      current: 'global-openkit-install',
+      installReadiness: 'managed',
+      installationMode: 'openkit-managed',
+    },
+  });
+  writeJson(path.join(projectRoot, '.openkit', 'openkit-install.json'), {
+    schema: 'openkit/install-state@1',
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: '0.1.0',
+    },
+    installation: {
+      profile: 'openkit-core',
+      status: 'installed',
+      installedAt: '2026-03-22T12:00:00.000Z',
+    },
+    assets: {
+      managed: [
+        { assetId: 'runtime.install-state', path: '.openkit/openkit-install.json', status: 'managed' },
+      ],
+      adopted: [
+        {
+          assetId: 'runtime.opencode-manifest',
+          path: 'opencode.json',
+          adoptedFrom: 'user-existing',
+          status: 'adopted',
+        },
+      ],
+    },
+    warnings: [],
+    conflicts: [],
+  });
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  const result = inspectManagedDoctor({
+    projectRoot,
+    env: {},
+    isOpenCodeAvailable: () => true,
+  });
+
+  assert.equal(result.status, 'healthy');
+  assert.equal(result.canRunCleanly, true);
+  assert.deepEqual(result.ownedAssets.adopted, ['opencode.json']);
+  assert.deepEqual(result.issues, []);
+});

package/tests/runtime/launcher.test.js

@@ -0,0 +1,230 @@
+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 {
+  CONFIG_DIR_RELATIVE_PATHS,
+  buildOpenCodeLayering,
+} from '../../src/runtime/opencode-layering.js';
+import { launchManagedOpenCode } from '../../src/runtime/launcher.js';
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'openkit-launcher-'));
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+test('buildOpenCodeLayering uses the managed config dir when no baseline config is set', () => {
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+    commands_dir: 'commands',
+  });
+
+  const result = buildOpenCodeLayering({ projectRoot, env: {} });
+
+  assert.equal(result.env.OPENCODE_CONFIG_DIR, path.join(projectRoot, '.opencode'));
+  assert.equal(result.env.OPENCODE_CONFIG_CONTENT, undefined);
+  assert.equal(result.managedConfig.runtimeManifestPath, path.join(projectRoot, '.opencode', 'opencode.json'));
+  assert.equal(result.baseline.configDir, null);
+  assert.equal(result.baseline.hasConfigContent, false);
+});
+
+test('buildOpenCodeLayering preserves baseline config while layering managed content', () => {
+  const projectRoot = makeTempDir();
+  const baselineConfigDir = path.join(projectRoot, 'user-config');
+
+  writeJson(path.join(baselineConfigDir, 'opencode.json'), {
+    commands_dir: 'user-commands',
+    hooks: {
+      config: 'user-hooks/hooks.json',
+    },
+  });
+
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+    agents_dir: 'agents',
+    commands_dir: 'commands',
+    hooks: {
+      config: 'hooks/hooks.json',
+    },
+  });
+
+  const result = buildOpenCodeLayering({
+    projectRoot,
+    env: {
+      OPENCODE_CONFIG_DIR: baselineConfigDir,
+      OPENCODE_CONFIG_CONTENT: JSON.stringify({
+        model: 'baseline-model',
+        customSetting: true,
+        skills_dir: 'user-skills',
+        hooks: {
+          enabled: true,
+        },
+      }),
+    },
+  });
+
+  assert.equal(result.env.OPENCODE_CONFIG_DIR, path.join(projectRoot, '.opencode'));
+
+  const layeredContent = JSON.parse(result.env.OPENCODE_CONFIG_CONTENT);
+  assert.equal(layeredContent.customSetting, true);
+  assert.equal(layeredContent.model, 'managed-model');
+  assert.equal(layeredContent.commands_dir, 'commands');
+  assert.equal(layeredContent.agents_dir, 'agents');
+  assert.equal(layeredContent.skills_dir, path.join(baselineConfigDir, 'user-skills'));
+  assert.deepEqual(layeredContent.hooks, {
+    enabled: true,
+    config: 'hooks/hooks.json',
+  });
+  assert.equal(result.baseline.configDir, baselineConfigDir);
+  assert.equal(result.baseline.config.commands_dir, path.join(baselineConfigDir, 'user-commands'));
+  assert.equal(
+    result.baseline.config.hooks.config,
+    path.join(baselineConfigDir, 'user-hooks', 'hooks.json')
+  );
+  assert.equal(result.baseline.config.model, 'baseline-model');
+});
+
+test('buildOpenCodeLayering only normalizes the documented config-dir-relative keys', () => {
+  const projectRoot = makeTempDir();
+  const baselineConfigDir = path.join(projectRoot, 'user-config');
+
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  const result = buildOpenCodeLayering({
+    projectRoot,
+    env: {
+      OPENCODE_CONFIG_DIR: baselineConfigDir,
+      OPENCODE_CONFIG_CONTENT: JSON.stringify({
+        model: 'baseline-model',
+        agents_dir: 'agents',
+        skills_dir: 'skills',
+        commands_dir: 'commands',
+        hooks: {
+          config: 'hooks/hooks.json',
+        },
+        otherRelativePath: 'notes/local.md',
+      }),
+    },
+  });
+
+  assert.deepEqual(CONFIG_DIR_RELATIVE_PATHS, ['agents_dir', 'commands_dir', 'skills_dir', 'hooks.config']);
+  assert.equal(result.baseline.config.agents_dir, path.join(baselineConfigDir, 'agents'));
+  assert.equal(result.baseline.config.skills_dir, path.join(baselineConfigDir, 'skills'));
+  assert.equal(result.baseline.config.commands_dir, path.join(baselineConfigDir, 'commands'));
+  assert.equal(result.baseline.config.hooks.config, path.join(baselineConfigDir, 'hooks', 'hooks.json'));
+  assert.equal(result.baseline.config.otherRelativePath, 'notes/local.md');
+});
+
+test('launchManagedOpenCode reports a clear error when opencode is unavailable', () => {
+  const projectRoot = makeTempDir();
+
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  const result = launchManagedOpenCode([], {
+    projectRoot,
+    env: {},
+    spawn: () => ({
+      error: Object.assign(new Error('spawn opencode ENOENT'), { code: 'ENOENT' }),
+      status: null,
+      stdout: '',
+      stderr: '',
+    }),
+  });
+
+  assert.equal(result.exitCode, 1);
+  assert.match(result.stderr, /Could not find `opencode` on your PATH/i);
+  assert.match(result.stderr, /supported launcher path is `openkit run`/i);
+});
+
+test('launchManagedOpenCode uses interactive stdio by default for the real launcher path', () => {
+  const projectRoot = makeTempDir();
+  let spawnCall = null;
+
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+  });
+
+  const result = launchManagedOpenCode(['status'], {
+    projectRoot,
+    env: {},
+    spawn: (command, args, options) => {
+      spawnCall = { command, args, options };
+      return { status: 0 };
+    },
+  });
+
+  assert.equal(result.exitCode, 0);
+  assert.equal(spawnCall.command, 'opencode');
+  assert.deepEqual(spawnCall.args, ['status']);
+  assert.equal(spawnCall.options.stdio, 'inherit');
+});
+
+test('launchManagedOpenCode forwards layered config to opencode on the supported path', () => {
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(projectRoot, 'bin');
+  const fakeOpencodePath = path.join(fakeBinDir, 'opencode');
+  const baselineConfigDir = path.join(projectRoot, 'user-config');
+
+  writeJson(path.join(baselineConfigDir, 'opencode.json'), {
+    skills_dir: 'baseline-skills',
+  });
+
+  writeJson(path.join(projectRoot, '.opencode', 'opencode.json'), {
+    model: 'managed-model',
+    commands_dir: 'commands',
+    agents_dir: 'agents',
+  });
+
+  fs.mkdirSync(fakeBinDir, { recursive: true });
+  fs.writeFileSync(
+    fakeOpencodePath,
+    [
+      '#!/usr/bin/env node',
+      'const payload = {',
+      '  args: process.argv.slice(2),',
+      '  configDir: process.env.OPENCODE_CONFIG_DIR ?? null,',
+      '  configContent: process.env.OPENCODE_CONFIG_CONTENT ?? null,',
+      '};',
+      'process.stdout.write(JSON.stringify(payload));',
+    ].join('\n'),
+    'utf8'
+  );
+  fs.chmodSync(fakeOpencodePath, 0o755);
+
+  const result = launchManagedOpenCode(['status'], {
+    projectRoot,
+    env: {
+      PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH ?? ''}`,
+      OPENCODE_CONFIG_DIR: baselineConfigDir,
+      OPENCODE_CONFIG_CONTENT: JSON.stringify({
+        customSetting: true,
+      }),
+    },
+    stdio: 'pipe',
+  });
+
+  assert.equal(result.exitCode, 0);
+
+  const payload = JSON.parse(result.stdout);
+  assert.deepEqual(payload.args, ['status']);
+  assert.equal(payload.configDir, path.join(projectRoot, '.opencode'));
+
+  const layeredContent = JSON.parse(payload.configContent);
+  assert.equal(layeredContent.customSetting, true);
+  assert.equal(layeredContent.model, 'managed-model');
+  assert.equal(layeredContent.commands_dir, 'commands');
+  assert.equal(layeredContent.agents_dir, 'agents');
+  assert.equal(layeredContent.skills_dir, path.join(baselineConfigDir, 'baseline-skills'));
+});

package/tests/runtime/module-boundary.test.js

@@ -0,0 +1,16 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+import fs from "node:fs"
+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, "..", "..")
+
+test(".opencode declares a CommonJS boundary for the legacy runtime", () => {
+  const packageJsonPath = path.join(worktreeRoot, ".opencode", "package.json")
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"))
+
+  assert.equal(packageJson.type, "commonjs")
+})