@duypham93/openkit 0.2.4 → 0.2.6

package/commands/write-plan.md

@@ -8,9 +8,10 @@ Use `/write-plan` to create an implementation plan for work currently in `Full D
 
 ## Global OpenKit path rule
 
-- In globally installed OpenKit sessions, resolve OpenKit-owned docs and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `AGENTS.md`, `context/`, `docs/templates/`, or `.opencode/`.
-- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
-- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+- In globally installed OpenKit sessions, treat `.opencode/openkit/` as the repo-local compatibility surface for OpenKit-owned docs, templates, and workflow tools.
+- Read canonical OpenKit docs from `.opencode/openkit/...`, not from repo-root `context/`, repo-root `AGENTS.md`, or repo-root `.opencode/`.
+- Use `.opencode/openkit/workflow-state.json` for resumable workflow state.
+- Use `node .opencode/openkit/workflow-state.js <command>` for workflow-state checks in global mode.
 
 ## Preconditions
 
@@ -21,13 +22,13 @@ Use `/write-plan` to create an implementation plan for work currently in `Full D
 
 ## Canonical docs to load
 
-- `AGENTS.md`
-- `context/navigation.md`
-- `context/core/workflow.md`
-- `context/core/project-config.md`
-- `.opencode/workflow-state.json`
-- `docs/templates/implementation-plan-template.md`
-- `docs/templates/migration-report-template.md` when migration work benefits from one running artifact
+- `.opencode/openkit/AGENTS.md`
+- `.opencode/openkit/context/navigation.md`
+- `.opencode/openkit/context/core/workflow.md`
+- `.opencode/openkit/context/core/project-config.md`
+- `.opencode/openkit/workflow-state.json`
+- `.opencode/openkit/docs/templates/implementation-plan-template.md`
+- `.opencode/openkit/docs/templates/migration-report-template.md` when migration work benefits from one running artifact
 - skill `writing-plans`
 
 For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
@@ -53,4 +54,4 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 - The plan should name the strongest real validation path available in the repository
 - In migration mode, use `migration_report` when handoffs would benefit from a single running narrative instead of scattered notes
 - If no repo-native app build, lint, or test command exists, say that explicitly in the plan instead of guessing a stack command
-- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` only to confirm workflow state, not to stand in for implementation verification
+- Use `node .opencode/openkit/workflow-state.js validate` only to confirm workflow state, not to stand in for implementation verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duypham93/openkit",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "files": [
     ".opencode/",

package/src/global/paths.js

@@ -82,5 +82,11 @@ export function getWorkspacePaths({ projectRoot, env = process.env, platform = p
     legacyRuntimeDir: path.join(resolvedProjectRoot, '.opencode'),
     legacyWorkflowStatePath: path.join(resolvedProjectRoot, '.opencode', 'workflow-state.json'),
     legacyWorkItemsDir: path.join(resolvedProjectRoot, '.opencode', 'work-items'),
+    workspaceShimDir: path.join(resolvedProjectRoot, '.opencode', 'openkit'),
+    workspaceShimContextDir: path.join(resolvedProjectRoot, '.opencode', 'openkit', 'context'),
+    workspaceShimTemplatesDir: path.join(resolvedProjectRoot, '.opencode', 'openkit', 'docs', 'templates'),
+    workspaceShimAgentsPath: path.join(resolvedProjectRoot, '.opencode', 'openkit', 'AGENTS.md'),
+    workspaceShimWorkflowStatePath: path.join(resolvedProjectRoot, '.opencode', 'openkit', 'workflow-state.json'),
+    workspaceShimWorkflowCliPath: path.join(resolvedProjectRoot, '.opencode', 'openkit', 'workflow-state.js'),
   };
 }

package/src/global/workspace-shim.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function removePathIfPresent(targetPath) {
+  try {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  } catch {
+    // ignore cleanup failures
+  }
+}
+
+function ensureParent(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function writeFile(filePath, content, mode) {
+  ensureParent(filePath);
+  fs.writeFileSync(filePath, content, 'utf8');
+  if (typeof mode === 'number') {
+    fs.chmodSync(filePath, mode);
+  }
+}
+
+function relativeTarget(fromPath, toPath) {
+  return path.relative(path.dirname(fromPath), toPath) || '.';
+}
+
+function createSymlinkOrCopy({ linkPath, targetPath, type = 'file' }) {
+  ensureParent(linkPath);
+
+  try {
+    if (fs.existsSync(linkPath) || fs.lstatSync(linkPath)) {
+      removePathIfPresent(linkPath);
+    }
+  } catch {
+    // ignore cleanup misses
+  }
+
+  try {
+    fs.symlinkSync(relativeTarget(linkPath, targetPath), linkPath, type);
+    return 'symlink';
+  } catch {
+    const stats = fs.statSync(targetPath);
+    if (stats.isDirectory()) {
+      fs.cpSync(targetPath, linkPath, { recursive: true });
+    } else {
+      fs.copyFileSync(targetPath, linkPath);
+    }
+    return 'copy';
+  }
+}
+
+function createIfMissing(createdPaths, { linkPath, targetPath, type = 'file' }) {
+  if (fs.existsSync(linkPath)) {
+    return null;
+  }
+
+  const mode = createSymlinkOrCopy({ linkPath, targetPath, type });
+  createdPaths.push(linkPath);
+  return mode;
+}
+
+export function ensureWorkspaceShim(paths) {
+  const createdPaths = [];
+
+  fs.mkdirSync(paths.workspaceShimDir, { recursive: true });
+
+  createIfMissing(createdPaths, {
+    linkPath: paths.workspaceShimAgentsPath,
+    targetPath: path.join(paths.kitRoot, 'AGENTS.md'),
+    type: 'file',
+  });
+
+  createIfMissing(createdPaths, {
+    linkPath: paths.workspaceShimContextDir,
+    targetPath: path.join(paths.kitRoot, 'context'),
+    type: 'dir',
+  });
+
+  createIfMissing(createdPaths, {
+    linkPath: paths.workspaceShimTemplatesDir,
+    targetPath: path.join(paths.kitRoot, 'docs', 'templates'),
+    type: 'dir',
+  });
+
+  createIfMissing(createdPaths, {
+    linkPath: paths.workspaceShimWorkflowStatePath,
+    targetPath: paths.workflowStatePath,
+    type: 'file',
+  });
+
+  const workflowCli = `#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const result = spawnSync(process.execPath, [${JSON.stringify(path.join(paths.kitRoot, '.opencode', 'workflow-state.js'))}, '--state', ${JSON.stringify(paths.workflowStatePath)}, ...args], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(typeof result.status === 'number' ? result.status : 1);
+`;
+
+  if (!fs.existsSync(paths.workspaceShimWorkflowCliPath)) {
+    writeFile(paths.workspaceShimWorkflowCliPath, workflowCli, 0o755);
+    createdPaths.push(paths.workspaceShimWorkflowCliPath);
+  }
+
+  createIfMissing(createdPaths, {
+    linkPath: path.join(paths.projectRoot, 'AGENTS.md'),
+    targetPath: paths.workspaceShimAgentsPath,
+    type: 'file',
+  });
+
+  createIfMissing(createdPaths, {
+    linkPath: path.join(paths.projectRoot, 'context'),
+    targetPath: paths.workspaceShimContextDir,
+    type: 'dir',
+  });
+
+  createIfMissing(createdPaths, {
+    linkPath: path.join(paths.projectRoot, '.opencode', 'workflow-state.json'),
+    targetPath: paths.workspaceShimWorkflowStatePath,
+    type: 'file',
+  });
+
+  if (!fs.existsSync(path.join(paths.projectRoot, '.opencode', 'workflow-state.js'))) {
+    const rootWorkflowCli = `#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const result = spawnSync(process.execPath, [${JSON.stringify(paths.workspaceShimWorkflowCliPath)}, ...args], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(typeof result.status === 'number' ? result.status : 1);
+`;
+
+    const rootWorkflowCliPath = path.join(paths.projectRoot, '.opencode', 'workflow-state.js');
+    writeFile(rootWorkflowCliPath, rootWorkflowCli, 0o755);
+    createdPaths.push(rootWorkflowCliPath);
+  }
+
+  if (!fs.existsSync(path.join(paths.projectRoot, '.opencode', 'work-items'))) {
+    createIfMissing(createdPaths, {
+      linkPath: path.join(paths.projectRoot, '.opencode', 'work-items'),
+      targetPath: paths.workItemsDir,
+      type: 'dir',
+    });
+  }
+
+  return {
+    paths,
+    createdPaths,
+  };
+}
+
+export function cleanupWorkspaceShim(shim) {
+  if (!shim?.createdPaths) {
+    return;
+  }
+
+  for (const createdPath of [...shim.createdPaths].reverse()) {
+    removePathIfPresent(createdPath);
+  }
+
+  const maybeShimDir = shim.paths?.workspaceShimDir;
+  if (maybeShimDir && fs.existsSync(maybeShimDir)) {
+    try {
+      const entries = fs.readdirSync(maybeShimDir);
+      if (entries.length === 0) {
+        removePathIfPresent(maybeShimDir);
+      }
+    } catch {
+      // ignore cleanup misses
+    }
+  }
+}

package/src/global/workspace-state.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { getWorkspacePaths } from './paths.js';
+import { ensureWorkspaceShim } from './workspace-shim.js';
 
 const WORKSPACE_STATE_SCHEMA = 'openkit/workspace-state@1';
 
@@ -50,7 +51,12 @@ export function ensureWorkspaceBootstrap(options = {}) {
     });
   }
 
-  return paths;
+  const shim = ensureWorkspaceShim(paths);
+
+  return {
+    ...paths,
+    workspaceShim: shim,
+  };
 }
 
 export function readWorkspaceMeta(options = {}) {

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

@@ -33,6 +33,10 @@ function writeExecutable(filePath, content) {
   fs.chmodSync(filePath, 0o755);
 }
 
+function removePathIfPresent(targetPath) {
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
 test('openkit --help shows global-install oriented help', () => {
   const result = runCli(['--help']);
 
@@ -222,6 +226,14 @@ process.stdout.write('mock opencode launched\\n');
   assert.equal(invocation.configDir, path.join(tempHome, 'kits', 'openkit'));
   assert.match(invocation.workflowState, /workspaces\/.*\/openkit\/\.opencode\/workflow-state\.json$/);
   assert.equal(invocation.kitRoot, path.join(tempHome, 'kits', 'openkit'));
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'AGENTS.md')), true);
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'context', 'core', 'workflow.md')), true);
+  assert.equal(fs.lstatSync(path.join(projectRoot, '.opencode', 'openkit', 'workflow-state.json')).isSymbolicLink() || fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'workflow-state.json')), true);
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'workflow-state.js')), true);
+  assert.equal(fs.existsSync(path.join(projectRoot, 'AGENTS.md')), true);
+  assert.equal(fs.existsSync(path.join(projectRoot, 'context', 'core', 'workflow.md')), true);
+  assert.equal(fs.lstatSync(path.join(projectRoot, '.opencode', 'workflow-state.json')).isSymbolicLink() || fs.existsSync(path.join(projectRoot, '.opencode', 'workflow-state.json')), true);
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'workflow-state.js')), true);
 });
 
 test('openkit run does not reinstall when the global install already exists', () => {
@@ -294,6 +306,65 @@ process.stdout.write('mock opencode launched after auto-install\\n');
   const invocation = readJson(logPath);
   assert.deepEqual(invocation.argv, [projectRoot]);
   assert.equal(invocation.kitRoot, path.join(tempHome, 'kits', 'openkit'));
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'AGENTS.md')), true);
+});
+
+test('openkit run does not overwrite existing repo-local workflow files when creating shims', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+
+  fs.mkdirSync(path.join(projectRoot, '.opencode'), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'context', 'core'), { recursive: true });
+  fs.writeFileSync(path.join(projectRoot, 'AGENTS.md'), 'project agents\n', 'utf8');
+  fs.writeFileSync(path.join(projectRoot, 'context', 'core', 'workflow.md'), 'project workflow\n', 'utf8');
+  fs.writeFileSync(path.join(projectRoot, '.opencode', 'workflow-state.json'), '{"project":true}\n', 'utf8');
+  fs.writeFileSync(path.join(projectRoot, '.opencode', 'workflow-state.js'), '#!/usr/bin/env node\n', 'utf8');
+
+  writeExecutable(path.join(fakeBinDir, 'opencode'), '#!/bin/sh\nexit 0\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.equal(fs.readFileSync(path.join(projectRoot, 'AGENTS.md'), 'utf8'), 'project agents\n');
+  assert.equal(fs.readFileSync(path.join(projectRoot, 'context', 'core', 'workflow.md'), 'utf8'), 'project workflow\n');
+  assert.equal(fs.readFileSync(path.join(projectRoot, '.opencode', 'workflow-state.json'), 'utf8'), '{"project":true}\n');
+  assert.equal(fs.readFileSync(path.join(projectRoot, '.opencode', 'workflow-state.js'), 'utf8'), '#!/usr/bin/env node\n');
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'AGENTS.md')), true);
+});
+
+test('openkit run cleans root compatibility shims when created files are removed', () => {
+  const tempHome = makeTempDir();
+  const projectRoot = makeTempDir();
+  const fakeBinDir = path.join(tempHome, 'bin');
+
+  writeExecutable(path.join(fakeBinDir, 'opencode'), '#!/bin/sh\nexit 0\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.equal(fs.existsSync(path.join(projectRoot, 'AGENTS.md')), true);
+
+  removePathIfPresent(path.join(projectRoot, 'AGENTS.md'));
+  removePathIfPresent(path.join(projectRoot, 'context'));
+  removePathIfPresent(path.join(projectRoot, '.opencode', 'workflow-state.json'));
+  removePathIfPresent(path.join(projectRoot, '.opencode', 'workflow-state.js'));
+
+  assert.equal(fs.existsSync(path.join(projectRoot, '.opencode', 'openkit', 'AGENTS.md')), true);
 });
 
 test('openkit run reports missing opencode after first-time setup completes', () => {