@duypham93/openkit 0.2.0

package/src/cli/commands/run.js

@@ -0,0 +1,63 @@
+import { ensureGlobalInstall } from '../../global/ensure-install.js';
+import { launchGlobalOpenKit } from '../../global/launcher.js';
+
+function runHelp() {
+  return [
+    'Usage: openkit run',
+    '',
+    'Run OpenCode with the globally installed OpenKit profile for the current project.',
+  ].join('\n');
+}
+
+export const runCommand = {
+  name: 'run',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${runHelp()}\n`);
+      return 0;
+    }
+
+    const ensured = ensureGlobalInstall({
+      projectRoot: process.cwd(),
+      env: process.env,
+    });
+
+    if (ensured.action === 'installed') {
+      io.stdout.write('OpenKit is not installed yet. Performing first-time setup...\n');
+      io.stdout.write(`Installed OpenKit globally.\n`);
+      io.stdout.write(`Kit root: ${ensured.install.kitRoot}\n`);
+      io.stdout.write(`Profile root: ${ensured.install.profilesRoot}\n`);
+    }
+
+    if (ensured.action === 'blocked' || (!ensured.doctor.canRunCleanly && ensured.doctor.status !== 'workspace-ready-with-issues')) {
+      for (const issue of ensured.doctor.issues ?? []) {
+        io.stderr.write(`${issue}\n`);
+      }
+
+      if (ensured.doctor.nextStep) {
+        io.stderr.write(`Next: ${ensured.doctor.nextStep}\n`);
+      }
+
+      return 1;
+    }
+
+    if (ensured.doctor.status === 'workspace-ready-with-issues') {
+      io.stderr.write('OpenKit setup is usable, but the workspace has issues.\n');
+    }
+
+    const result = launchGlobalOpenKit(args, {
+      projectRoot: process.cwd(),
+      env: process.env,
+    });
+
+    if (result.stdout) {
+      io.stdout.write(result.stdout);
+    }
+
+    if (result.stderr) {
+      io.stderr.write(result.stderr);
+    }
+
+    return result.exitCode;
+  },
+};

package/src/cli/commands/uninstall.js

@@ -0,0 +1,32 @@
+import { uninstallGlobalOpenKit } from '../../global/uninstall.js';
+
+function uninstallHelp() {
+  return [
+    'Usage: openkit uninstall [--remove-workspaces]',
+    '',
+    'Remove the globally installed OpenKit kit and profile from the OpenCode home directory.',
+  ].join('\n');
+}
+
+export const uninstallCommand = {
+  name: 'uninstall',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${uninstallHelp()}\n`);
+      return 0;
+    }
+
+    const result = uninstallGlobalOpenKit({
+      env: process.env,
+      removeWorkspaces: args.includes('--remove-workspaces'),
+    });
+
+    io.stdout.write('Uninstalled OpenKit global kit.\n');
+    if (result.removedWorkspaces) {
+      io.stdout.write('Workspace state was removed.\n');
+    } else {
+      io.stdout.write('Workspace state was preserved.\n');
+    }
+    return 0;
+  },
+};

package/src/cli/commands/upgrade.js

@@ -0,0 +1,25 @@
+import { materializeGlobalInstall } from '../../global/materialize.js';
+
+function upgradeHelp() {
+  return [
+    'Usage: openkit upgrade',
+    '',
+    'Refresh the globally installed OpenKit kit in the OpenCode home directory.',
+    'Use this when the global install needs to be repaired or refreshed.',
+  ].join('\n');
+}
+
+export const upgradeCommand = {
+  name: 'upgrade',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${upgradeHelp()}\n`);
+      return 0;
+    }
+
+    const result = materializeGlobalInstall({ env: process.env });
+    io.stdout.write('Upgraded OpenKit global install.\n');
+    io.stdout.write(`Kit root: ${result.kitRoot}\n`);
+    return 0;
+  },
+};

package/src/cli/conflict-output.js

@@ -0,0 +1,19 @@
+function formatConflict(conflict) {
+  const details = [conflict.path];
+
+  if (conflict.reason) {
+    details.push(`reason=${conflict.reason}`);
+  }
+
+  if (conflict.resolution) {
+    details.push(`resolution=${conflict.resolution}`);
+  }
+
+  return `- ${details.join(' | ')}`;
+}
+
+export function writeConflictReport(io, commandName, conflicts) {
+  io.stderr.write(
+    `${commandName} aborted due to conflicts.\n${conflicts.map((conflict) => formatConflict(conflict)).join('\n')}\n`
+  );
+}

package/src/cli/index.js

@@ -0,0 +1,56 @@
+import { helpCommand } from './commands/help.js';
+import { initCommand } from './commands/init.js';
+import { installCommand } from './commands/install.js';
+import { installGlobalCommand } from './commands/install-global.js';
+import { runCommand } from './commands/run.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { uninstallCommand } from './commands/uninstall.js';
+import { doctorCommand } from './commands/doctor.js';
+import { detectVietnameseCommand } from './commands/detect-vietnamese.js';
+
+const commands = {
+  help: helpCommand,
+  init: initCommand,
+  install: installCommand,
+  'install-global': installGlobalCommand,
+  run: runCommand,
+  upgrade: upgradeCommand,
+  uninstall: uninstallCommand,
+  doctor: doctorCommand,
+  'internal-audit-vietnamese': detectVietnameseCommand,
+};
+
+export async function runCli(argv, io = defaultIo()) {
+  const args = Array.isArray(argv) ? argv : [];
+  const [commandName, ...rest] = args;
+
+  if (!commandName || commandName === '--help' || commandName === '-h') {
+    return helpCommand.run([], io, { commands });
+  }
+
+  if (commandName === 'help') {
+    return helpCommand.run(rest, io, { commands });
+  }
+
+  const command = commands[commandName];
+
+  if (!command) {
+    io.stderr.write(
+      `Unknown command: ${commandName}\nRun \`openkit --help\` to see available commands.\n`
+    );
+    return 1;
+  }
+
+  if (rest.includes('--help') || rest.includes('-h')) {
+    return command.run(['--help'], io, { commands });
+  }
+
+  return command.run(rest, io, { commands });
+}
+
+function defaultIo() {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}

package/src/global/doctor.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readJsonIfPresent, validateGlobalInstallState } from './install-state.js';
+import { ensureWorkspaceBootstrap, readWorkspaceMeta } from './workspace-state.js';
+import { getGlobalPaths, getWorkspacePaths } from './paths.js';
+
+function isOpenCodeAvailable(env = process.env) {
+  const pathValue = env.PATH ?? '';
+  return pathValue.split(path.delimiter).some((segment) => segment && fs.existsSync(path.join(segment, 'opencode')));
+}
+
+function withGuidance(result, nextStep, recommendedCommand = null) {
+  return {
+    ...result,
+    nextStep,
+    recommendedCommand,
+  };
+}
+
+export function inspectGlobalDoctor({ projectRoot = process.cwd(), env = process.env } = {}) {
+  const globalPaths = getGlobalPaths({ env });
+  const workspacePaths = getWorkspacePaths({ projectRoot, env });
+  const globalInstallState = readJsonIfPresent(globalPaths.installStatePath);
+  const profileManifest = readJsonIfPresent(globalPaths.profileManifestPath);
+
+  const issues = [];
+
+  if (!globalInstallState) {
+    return withGuidance({
+      status: 'install-missing',
+      canRunCleanly: false,
+      globalPaths,
+      workspacePaths,
+      issues: ['Global OpenKit install was not found.'],
+    }, 'Run openkit run for first-time setup.', 'openkit run');
+  }
+
+  const installStateErrors = validateGlobalInstallState(globalInstallState);
+  if (installStateErrors.length > 0) {
+    return withGuidance({
+      status: 'install-invalid',
+      canRunCleanly: false,
+      globalPaths,
+      workspacePaths,
+      issues: installStateErrors,
+    }, 'Run openkit upgrade to refresh the global install.', 'openkit upgrade');
+  }
+
+  if (!profileManifest) {
+    issues.push('OpenCode profile manifest for openkit is missing.');
+  }
+
+  if (!fs.existsSync(path.join(globalPaths.kitRoot, '.opencode', 'workflow-state.js'))) {
+    issues.push('Global workflow-state CLI is missing from the installed kit.');
+  }
+
+  if (!isOpenCodeAvailable(env)) {
+    issues.push('OpenCode executable is not available on PATH.');
+  }
+
+  const workspace = readWorkspaceMeta({ projectRoot, env });
+  ensureWorkspaceBootstrap({ projectRoot, env });
+
+  return withGuidance({
+    status: issues.length === 0 ? 'healthy' : 'workspace-ready-with-issues',
+    canRunCleanly: issues.length === 0,
+    globalPaths,
+    workspacePaths,
+    workspace,
+    issues,
+  }, issues.length === 0 ? 'Run openkit run.' : 'Review the issues above before relying on this workspace.', issues.length === 0 ? 'openkit run' : null);
+}
+
+export function renderGlobalDoctorSummary(result) {
+  const lines = [
+    `Status: ${result.status}`,
+    `Global kit root: ${result.globalPaths.kitRoot}`,
+    `Workspace root: ${result.workspacePaths.workspaceRoot}`,
+    `Project root: ${result.workspacePaths.projectRoot}`,
+    `Workspace id: ${result.workspacePaths.workspaceId}`,
+    `Can run cleanly: ${result.canRunCleanly ? 'yes' : 'no'}`,
+  ];
+
+  if (Array.isArray(result.issues) && result.issues.length > 0) {
+    lines.push('Issues:');
+    for (const issue of result.issues) {
+      lines.push(`- ${issue}`);
+    }
+  }
+
+  if (result.nextStep) {
+    lines.push(`Next: ${result.nextStep}`);
+  }
+
+  if (result.recommendedCommand) {
+    lines.push(`Recommended command: ${result.recommendedCommand}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/src/global/ensure-install.js

@@ -0,0 +1,32 @@
+import { inspectGlobalDoctor } from './doctor.js';
+import { materializeGlobalInstall } from './materialize.js';
+
+export function ensureGlobalInstall({ projectRoot = process.cwd(), env = process.env } = {}) {
+  const initialDoctor = inspectGlobalDoctor({ projectRoot, env });
+
+  if (initialDoctor.status === 'install-invalid') {
+    return {
+      action: 'blocked',
+      installed: false,
+      doctor: initialDoctor,
+    };
+  }
+
+  if (initialDoctor.status !== 'install-missing') {
+    return {
+      action: 'none',
+      installed: false,
+      doctor: initialDoctor,
+    };
+  }
+
+  const install = materializeGlobalInstall({ env });
+  const doctor = inspectGlobalDoctor({ projectRoot, env });
+
+  return {
+    action: doctor.canRunCleanly || doctor.status === 'workspace-ready-with-issues' ? 'installed' : 'blocked',
+    installed: true,
+    install,
+    doctor,
+  };
+}

package/src/global/install-state.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const GLOBAL_INSTALL_SCHEMA = 'openkit/global-install-state@1';
+
+export function createGlobalInstallState({ kitVersion = '0.1.0', installedAt = new Date().toISOString(), profile = 'openkit' } = {}) {
+  return {
+    schema: GLOBAL_INSTALL_SCHEMA,
+    stateVersion: 1,
+    kit: {
+      name: 'OpenKit',
+      version: kitVersion,
+    },
+    installation: {
+      profile,
+      status: 'installed',
+      installedAt,
+    },
+  };
+}
+
+export function readJsonIfPresent(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export function validateGlobalInstallState(state) {
+  const errors = [];
+
+  if (!state || typeof state !== 'object') {
+    return ['global install state must be an object'];
+  }
+
+  if (state.schema !== GLOBAL_INSTALL_SCHEMA) {
+    errors.push(`schema must be '${GLOBAL_INSTALL_SCHEMA}'`);
+  }
+
+  if (state.stateVersion !== 1) {
+    errors.push('stateVersion must be 1');
+  }
+
+  if (!state.kit?.name || typeof state.kit.name !== 'string') {
+    errors.push('kit.name must be a non-empty string');
+  }
+
+  if (!state.kit?.version || typeof state.kit.version !== 'string') {
+    errors.push('kit.version must be a non-empty string');
+  }
+
+  if (!state.installation?.profile || typeof state.installation.profile !== 'string') {
+    errors.push('installation.profile must be a non-empty string');
+  }
+
+  if (state.installation?.status !== 'installed') {
+    errors.push("installation.status must be 'installed'");
+  }
+
+  if (!state.installation?.installedAt || typeof state.installation.installedAt !== 'string') {
+    errors.push('installation.installedAt must be an ISO timestamp string');
+  }
+
+  return errors;
+}
+
+export { GLOBAL_INSTALL_SCHEMA };

package/src/global/launcher.js

@@ -0,0 +1,51 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { ensureWorkspaceBootstrap } from './workspace-state.js';
+
+function formatMissingOpenCodeError() {
+  return [
+    'Could not find `opencode` on your PATH.',
+    'Install OpenCode or add `opencode` to PATH, then retry `openkit run`.',
+  ].join('\n');
+}
+
+export function launchGlobalOpenKit(args = [], { projectRoot = process.cwd(), env = process.env, spawn = spawnSync, stdio = 'inherit' } = {}) {
+  const paths = ensureWorkspaceBootstrap({ projectRoot, env });
+  const launcherEnv = {
+    ...env,
+    OPENKIT_GLOBAL_MODE: '1',
+    OPENKIT_PROJECT_ROOT: paths.projectRoot,
+    OPENKIT_WORKFLOW_STATE: paths.workflowStatePath,
+    OPENKIT_KIT_ROOT: paths.kitRoot,
+    OPENKIT_HOME: paths.openCodeHome,
+    OPENCODE_CONFIG_DIR: paths.profilesRoot,
+  };
+
+  const result = spawn('opencode', ['--profile', 'openkit', ...args], {
+    cwd: paths.projectRoot,
+    env: launcherEnv,
+    encoding: 'utf8',
+    stdio,
+  });
+
+  if (result.error?.code === 'ENOENT') {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: `${formatMissingOpenCodeError()}\n`,
+      paths,
+    };
+  }
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return {
+    exitCode: typeof result.status === 'number' ? result.status : 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    paths,
+  };
+}

package/src/global/materialize.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createGlobalInstallState, writeJson } from './install-state.js';
+import { getGlobalPaths } from './paths.js';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(MODULE_DIR, '../..');
+
+const GLOBAL_KIT_ASSETS = [
+  '.opencode',
+  'agents',
+  'skills',
+  'commands',
+  'context',
+  'hooks',
+  'docs',
+  'registry.json',
+  'AGENTS.md',
+  'README.md',
+];
+
+function removePathIfPresent(targetPath) {
+  if (!fs.existsSync(targetPath)) {
+    return;
+  }
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function copyAsset(sourcePath, targetPath) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const stats = fs.statSync(sourcePath);
+
+  if (stats.isDirectory()) {
+    fs.cpSync(sourcePath, targetPath, { recursive: true });
+    return;
+  }
+
+  fs.copyFileSync(sourcePath, targetPath);
+}
+
+function listManagedFiles(kitRoot) {
+  const files = [];
+
+  function walk(currentPath) {
+    for (const entry of fs.readdirSync(currentPath, { withFileTypes: true })) {
+      const entryPath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryPath);
+      } else {
+        files.push(path.relative(kitRoot, entryPath));
+      }
+    }
+  }
+
+  walk(kitRoot);
+  return files.sort();
+}
+
+function createProfileManifest(kitRoot, profileHooksPath) {
+  const kitManifestPath = path.join(kitRoot, '.opencode', 'opencode.json');
+  const kitManifest = JSON.parse(fs.readFileSync(kitManifestPath, 'utf8'));
+
+  return {
+    model: kitManifest.model,
+    agents_dir: path.join(kitRoot, 'agents'),
+    skills_dir: path.join(kitRoot, 'skills'),
+    commands_dir: path.join(kitRoot, 'commands'),
+    hooks: {
+      config: profileHooksPath,
+    },
+    openkit: {
+      profile: 'openkit',
+      kit_root: kitRoot,
+      manifest: kitManifestPath,
+    },
+  };
+}
+
+export function materializeGlobalInstall({ env = process.env, kitVersion = '0.1.0' } = {}) {
+  const paths = getGlobalPaths({ env });
+
+  removePathIfPresent(paths.kitRoot);
+  removePathIfPresent(paths.profilesRoot);
+
+  fs.mkdirSync(paths.kitRoot, { recursive: true });
+  fs.mkdirSync(paths.profilesRoot, { recursive: true });
+
+  for (const relativeAsset of GLOBAL_KIT_ASSETS) {
+    copyAsset(path.join(PACKAGE_ROOT, relativeAsset), path.join(paths.kitRoot, relativeAsset));
+  }
+
+  const installState = createGlobalInstallState({ kitVersion, profile: 'openkit' });
+  writeJson(paths.installStatePath, installState);
+  writeJson(paths.profileManifestPath, createProfileManifest(paths.kitRoot, paths.profileHooksPath));
+  writeJson(paths.profileHooksPath, {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: 'startup|clear|compact',
+          hooks: [
+            {
+              type: 'command',
+              command: `${path.join(paths.kitRoot, 'hooks', 'session-start')}`,
+              async: false,
+            },
+          ],
+        },
+      ],
+    },
+  });
+  writeJson(paths.managedFilesPath, {
+    schema: 'openkit/managed-files@1',
+    generatedAt: new Date().toISOString(),
+    files: listManagedFiles(paths.kitRoot),
+  });
+
+  return {
+    ...paths,
+    installState,
+  };
+}

package/src/global/paths.js

@@ -0,0 +1,85 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function normalizeWorkspaceSeed(projectRoot, platform = process.platform) {
+  const resolved = path.resolve(projectRoot);
+  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+export function getOpenCodeHome({ env = process.env, platform = process.platform, homedir = os.homedir() } = {}) {
+  if (env.OPENCODE_HOME) {
+    return path.resolve(env.OPENCODE_HOME);
+  }
+
+  if (platform === 'win32') {
+    const base = env.APPDATA || path.join(homedir, 'AppData', 'Roaming');
+    return path.join(base, 'opencode');
+  }
+
+  const base = env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(homedir, '.config');
+  return path.join(base, 'opencode');
+}
+
+export function detectProjectRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (fs.existsSync(path.join(current, '.git')) || fs.existsSync(path.join(current, 'package.json'))) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(startDir);
+    }
+    current = parent;
+  }
+}
+
+export function createWorkspaceId(projectRoot, { platform = process.platform } = {}) {
+  const seed = normalizeWorkspaceSeed(projectRoot, platform);
+  return crypto.createHash('sha256').update(seed).digest('hex').slice(0, 16);
+}
+
+export function getGlobalPaths(options = {}) {
+  const openCodeHome = getOpenCodeHome(options);
+  const kitRoot = path.join(openCodeHome, 'kits', 'openkit');
+  const profilesRoot = path.join(openCodeHome, 'profiles', 'openkit');
+  const workspacesRoot = path.join(openCodeHome, 'workspaces');
+
+  return {
+    openCodeHome,
+    kitRoot,
+    installStatePath: path.join(kitRoot, 'install-state.json'),
+    managedFilesPath: path.join(kitRoot, 'managed-files.json'),
+    profilesRoot,
+    profileManifestPath: path.join(profilesRoot, 'opencode.json'),
+    profileHooksPath: path.join(profilesRoot, 'hooks.json'),
+    workspacesRoot,
+  };
+}
+
+export function getWorkspacePaths({ projectRoot, env = process.env, platform = process.platform, homedir = os.homedir() } = {}) {
+  const resolvedProjectRoot = detectProjectRoot(projectRoot ?? process.cwd());
+  const globalPaths = getGlobalPaths({ env, platform, homedir });
+  const workspaceId = createWorkspaceId(resolvedProjectRoot, { platform });
+  const workspaceRoot = path.join(globalPaths.workspacesRoot, workspaceId, 'openkit');
+  const opencodeDir = path.join(workspaceRoot, '.opencode');
+
+  return {
+    ...globalPaths,
+    projectRoot: resolvedProjectRoot,
+    workspaceId,
+    workspaceRoot,
+    workspaceMetaPath: path.join(workspaceRoot, 'workspace.json'),
+    opencodeDir,
+    workflowStatePath: path.join(opencodeDir, 'workflow-state.json'),
+    workItemsDir: path.join(opencodeDir, 'work-items'),
+    workItemIndexPath: path.join(opencodeDir, 'work-items', 'index.json'),
+    legacyRuntimeDir: path.join(resolvedProjectRoot, '.opencode'),
+    legacyWorkflowStatePath: path.join(resolvedProjectRoot, '.opencode', 'workflow-state.json'),
+    legacyWorkItemsDir: path.join(resolvedProjectRoot, '.opencode', 'work-items'),
+  };
+}

package/src/global/uninstall.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+
+import { getGlobalPaths } from './paths.js';
+
+function removeIfPresent(targetPath) {
+  if (fs.existsSync(targetPath)) {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+}
+
+export function uninstallGlobalOpenKit({ env = process.env, removeWorkspaces = false } = {}) {
+  const paths = getGlobalPaths({ env });
+
+  removeIfPresent(paths.kitRoot);
+  removeIfPresent(paths.profilesRoot);
+
+  if (removeWorkspaces) {
+    removeIfPresent(paths.workspacesRoot);
+  }
+
+  return {
+    ...paths,
+    removedWorkspaces: removeWorkspaces,
+  };
+}