@ikieaneh/opencode-kit 0.6.0 → 0.6.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-kit",
   "description": "Standardized orchestration framework — contract-based, rules-enforced, zero-touch agent workflow",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "author": {
     "name": "Rizki Rachman",
     "url": "https://github.com/RizkiRachman"

package/.opencode/plugins/opencode-kit.js

@@ -73,33 +73,38 @@ const resolveConfigPath = (projectDir, relPath) => {
 
 // --- Auto-init contract.json if missing ---
 const ensureContract = (projectDir) => {
-  const homeDir = os.homedir();
-  const globalDir = path.join(homeDir, '.config/opencode-kit');
-  const contractPath = path.join(projectDir, '.opencode', 'orchestration', 'contract.json');
-
-  // Already exists — nothing to do
-  if (fs.existsSync(contractPath)) return contractPath;
-
-  // Check global config first
-  const globalContract = path.join(globalDir, 'orchestration', 'contract.json');
-  if (fs.existsSync(globalContract)) {
-    fs.mkdirSync(path.dirname(contractPath), { recursive: true });
-    fs.copyFileSync(globalContract, contractPath);
-    log('info', `Auto-initialized contract from global config: ${contractPath}`);
-    return contractPath;
-  }
+  try {
+    const homeDir = os.homedir();
+    const globalDir = path.join(homeDir, '.config/opencode-kit');
+    const contractPath = path.join(projectDir, '.opencode', 'orchestration', 'contract.json');
+
+    // Already exists — nothing to do
+    if (fs.existsSync(contractPath)) return contractPath;
+
+    // Check global config first
+    const globalContract = path.join(globalDir, 'orchestration', 'contract.json');
+    if (fs.existsSync(globalContract)) {
+      fs.mkdirSync(path.dirname(contractPath), { recursive: true });
+      fs.copyFileSync(globalContract, contractPath);
+      log('info', `Auto-initialized contract from global config: ${contractPath}`);
+      return contractPath;
+    }
 
-  // Scaffold from plugin template
-  const templatePath = path.join(TEMPLATES_DIR, 'contract.json');
-  if (fs.existsSync(templatePath)) {
-    fs.mkdirSync(path.dirname(contractPath), { recursive: true });
-    fs.copyFileSync(templatePath, contractPath);
-    log('info', `Auto-initialized contract from plugin template: ${contractPath}`);
-    return contractPath;
-  }
+    // Scaffold from plugin template
+    const templatePath = path.join(TEMPLATES_DIR, 'contract.json');
+    if (fs.existsSync(templatePath)) {
+      fs.mkdirSync(path.dirname(contractPath), { recursive: true });
+      fs.copyFileSync(templatePath, contractPath);
+      log('info', `Auto-initialized contract from plugin template: ${contractPath}`);
+      return contractPath;
+    }
 
-  log('warn', 'Could not auto-initialize contract — no template found');
-  return null;
+    log('warn', 'Could not auto-initialize contract — no template found');
+    return null;
+  } catch (err) {
+    log('error', `Failed to auto-init contract: ${err.message}`);
+    return null;
+  }
 };
 
 // --- Load bootstrap content (cached) ---
@@ -160,64 +165,98 @@ export const OpencodeKitPlugin = async ({ client, directory }) => {
   ensureContract(projectDir);
 
   // Ensure global config directory exists
-  fs.mkdirSync(path.join(globalConfigDir, 'orchestration'), { recursive: true });
-  fs.mkdirSync(path.join(globalConfigDir, 'rules'), { recursive: true });
+  try {
+    fs.mkdirSync(path.join(globalConfigDir, 'orchestration'), { recursive: true });
+    fs.mkdirSync(path.join(globalConfigDir, 'rules'), { recursive: true });
+  } catch (err) {
+    log('warn', `Failed to create global config dirs: ${err.message}`);
+  }
 
   return {
     // Skill resolution order (first match wins):
     //   1. .opencode/skills/<name>/  (user project — highest priority)
     //   2. plugin skills/<name>/     (opencode-kit defaults — fallback)
     config: async (config) => {
-      config.skills = config.skills || {};
-      config.skills.paths = config.skills.paths || [];
-
-      // Detect if other plugins might conflict with opencode-kit's system prompt
-      if (config.plugins && Array.isArray(config.plugins)) {
-        const kitIndex = config.plugins.findIndex(p =>
-          typeof p === 'string' && p.includes('opencode-kit')
-        );
-        if (kitIndex > 0) {
-          const firstPlugin = config.plugins[0];
-          log('warn', `Plugin ordering conflict: opencode-kit should be FIRST, but found '${firstPlugin}' at position 0 and opencode-kit at position ${kitIndex}`);
+      try {
+        config.skills = config.skills || {};
+        config.skills.paths = config.skills.paths || [];
+
+        // Detect if other plugins might conflict with opencode-kit's system prompt
+        if (config.plugins && Array.isArray(config.plugins)) {
+          const kitIndex = config.plugins.findIndex(p =>
+            typeof p === 'string' && p.includes('opencode-kit')
+          );
+          if (kitIndex > 0) {
+            const firstPlugin = config.plugins[0];
+            log('warn', `Plugin ordering conflict: opencode-kit should be FIRST, but found '${firstPlugin}' at position 0 and opencode-kit at position ${kitIndex}`);
+          }
         }
-      }
 
-      // Register user project skills FIRST (higher priority)
-      const userSkillsDir = path.join(projectDir, '.opencode/skills');
-      if (fs.existsSync(userSkillsDir) && !config.skills.paths.includes(userSkillsDir)) {
-        config.skills.paths.push(userSkillsDir);
-        log('info', `Registered user skills: ${userSkillsDir}`);
-      }
+        // Register user project skills FIRST (higher priority)
+        const userSkillsDir = path.join(projectDir, '.opencode/skills');
+        if (fs.existsSync(userSkillsDir) && !config.skills.paths.includes(userSkillsDir)) {
+          config.skills.paths.push(userSkillsDir);
+          log('info', `Registered user skills: ${userSkillsDir}`);
+        }
 
-      // Register plugin skills SECOND (fallback)
-      if (!config.skills.paths.includes(SKILLS_DIR)) {
-        config.skills.paths.push(SKILLS_DIR);
-        log('info', `Registered plugin skills: ${SKILLS_DIR}`);
-      }
+        // Register plugin skills SECOND (fallback)
+        if (!config.skills.paths.includes(SKILLS_DIR)) {
+          config.skills.paths.push(SKILLS_DIR);
+          log('info', `Registered plugin skills: ${SKILLS_DIR}`);
+        }
 
-      // Register global config skills path
-      if (!config.skills.paths.includes(globalConfigDir)) {
-        if (fs.existsSync(globalConfigDir)) {
-          config.skills.paths.push(globalConfigDir);
+        // Register global config skills path
+        if (!config.skills.paths.includes(globalConfigDir)) {
+          if (fs.existsSync(globalConfigDir)) {
+            config.skills.paths.push(globalConfigDir);
+          }
         }
-      }
 
-      // Provide default contract key hint for agents
-      config.contractKey = contractKey;
+        // Provide default contract key hint for agents
+        config.contractKey = contractKey;
+      } catch (err) {
+        log('error', `config hook failed: ${err.message}`);
+      }
     },
 
     'experimental.chat.messages.transform': async (_input, output) => {
-      const bootstrap = getBootstrapContent();
-      if (!bootstrap || !output.messages.length) return;
+      try {
+        const bootstrap = getBootstrapContent();
+        if (!bootstrap || !output.messages.length) return;
+
+        // Check contract for rule_overrides and inject them into bootstrap
+        const contractPath = path.join(projectDir, '.opencode', 'orchestration', 'contract.json');
+        let finalBootstrap = bootstrap;
+        if (fs.existsSync(contractPath)) {
+          try {
+            const contractRaw = fs.readFileSync(contractPath, 'utf8');
+            const contract = JSON.parse(contractRaw);
+            if (contract.validation && contract.validation.rule_overrides) {
+              const overrides = contract.validation.rule_overrides;
+              const overrideKeys = Object.keys(overrides);
+              if (overrideKeys.length > 0) {
+                const overrideText = overrideKeys
+                  .map(id => `  - ${id}: action → ${overrides[id]}`)
+                  .join('\n');
+                finalBootstrap = bootstrap + `\n## Rule Overrides (from contract)\n\nThe following rule severities have been overridden:\n${overrideText}\n`;
+              }
+            }
+          } catch (err) {
+            log('warn', `Failed to parse contract for rule_overrides: ${err.message}`);
+          }
+        }
 
-      const firstUser = output.messages.find(m => m.info.role === 'user');
-      if (!firstUser || !firstUser.parts.length) return;
+        const firstUser = output.messages.find(m => m.info.role === 'user');
+        if (!firstUser || !firstUser.parts.length) return;
 
-      // Guard: skip if already injected
-      if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('opencode-kit'))) return;
+        // Guard: skip if already injected
+        if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('opencode-kit'))) return;
 
-      const ref = firstUser.parts[0];
-      firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
+        const ref = firstUser.parts[0];
+        firstUser.parts.unshift({ ...ref, type: 'text', text: finalBootstrap });
+      } catch (err) {
+        log('error', `messages.transform hook failed: ${err.message}`);
+      }
     }
   };
 };

package/docs/examples/QUICKSTART.md

@@ -66,7 +66,7 @@ Create `opencode.json`:
       "steps": 30,
       "tools": { "postgres_*": false, "memory_*": false, "graphify_*": false }
     },
-    "leaner": {
+    "learner": {
       "model": "your-model",
       "skills": ["verification-before-completion", "qa-expert"]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",
@@ -41,6 +41,10 @@
     "type": "git",
     "url": "git+https://github.com/RizkiRachman/opencode-kit.git"
   },
+  "scripts": {
+    "lint": "eslint src/ test/",
+    "format": "prettier --check src/ test/"
+  },
   "bugs": {
     "url": "https://github.com/RizkiRachman/opencode-kit/issues"
   },

package/src/adr.sh

@@ -59,24 +59,31 @@ if [ -z "$TITLE" ]; then
 fi
 
 # --- Compute next ADR ID ---
-NEXT_ID=$($PYTHON_CMD -c "
-import json
-with open('$CONTRACT_FILE') as f: d = json.load(f)
+NEXT_ID=$(CONTRACT_FILE="$CONTRACT_FILE" $PYTHON_CMD -c "
+import json, os
+with open(os.environ['CONTRACT_FILE']) as f: d = json.load(f)
 log = d.get('decisions', {}).get('adr_log', [])
 if not log:
   print('ADR-001')
 else:
-  last = max(int(entry.get('id','ADR-000').replace('ADR-','')) for entry in log)
+  last = 0
+  for entry in log:
+    try:
+      num = int(entry.get('id','ADR-000').replace('ADR-',''))
+      if num > last: last = num
+    except ValueError:
+      continue
   print(f'ADR-{last+1:03d}')
 ")
 
 # --- Check for duplicate title ---
-DUP=$($PYTHON_CMD -c "
-import json
-with open('$CONTRACT_FILE') as f: d = json.load(f)
+DUP=$(CONTRACT_FILE="$CONTRACT_FILE" TITLE="$TITLE" $PYTHON_CMD -c "
+import json, os
+with open(os.environ['CONTRACT_FILE']) as f: d = json.load(f)
 log = d.get('decisions', {}).get('adr_log', [])
+search_title = os.environ.get('TITLE', '').lower().strip()
 for entry in log:
-  if entry.get('title','').lower().strip() == '$TITLE'.lower().strip():
+  if entry.get('title','').lower().strip() == search_title:
     print(entry.get('id',''))
     break
 " 2>/dev/null)
@@ -86,50 +93,37 @@ if [ -n "$DUP" ]; then
   exit 0
 fi
 
-# --- Build ADR entry via temp JSON file (avoids shell injection) ---
-# Write ADR fields to temp file to avoid shell interpolation into Python
-ADR_DATA=$(mktemp /tmp/opencode-adr-data-XXXXX.json)
-cat > "$ADR_DATA" << ADRDATA
-{
-  "title": "$TITLE",
-  "context": "$CONTEXT",
-  "decision": "$DECISION",
-  "alternatives": "$ALTERNATIVES",
-  "consequences": "$CONSEQUENCES"
-}
-ADRDATA
-
-$PYTHON_CMD -c "
-import json
+# --- Build ADR entry via Python (avoids shell injection) ---
+ENTRY_FILE=$(mktemp /tmp/opencode-adr-entry-XXXXX.json)
+trap 'rm -f "$ENTRY_FILE"' EXIT INT TERM
 
-with open('$ADR_DATA') as f:
-    data = json.load(f)
+TITLE="$TITLE" CONTEXT="$CONTEXT" DECISION="$DECISION" ALTERNATIVES="$ALTERNATIVES" CONSEQUENCES="$CONSEQUENCES" NEXT_ID="$NEXT_ID" ENTRY_FILE="$ENTRY_FILE" $PYTHON_CMD -c "
+import json, os
+from datetime import date
 
 entry = {
-  'id': '$NEXT_ID',
-  'date': '$(date +%Y-%m-%d)',
-  'title': data['title'],
-  'context': data['context'],
-  'decision': data['decision'],
-  'alternatives': data['alternatives'],
-  'consequences': data['consequences']
+    'id': os.environ['NEXT_ID'],
+    'date': date.today().isoformat(),
+    'title': os.environ.get('TITLE', ''),
+    'context': os.environ.get('CONTEXT', ''),
+    'decision': os.environ.get('DECISION', ''),
+    'alternatives': os.environ.get('ALTERNATIVES', ''),
+    'consequences': os.environ.get('CONSEQUENCES', '')
 }
 
-with open('/tmp/opencode-adr-entry.json', 'w') as f:
+with open(os.environ['ENTRY_FILE'], 'w') as f:
     json.dump(entry, f, indent=2)
 print('Entry written')
 "
 
-rm -f "$ADR_DATA"
-
 # --- Inject into contract.json ---
-$PYTHON_CMD -c "
-import json
+CONTRACT_FILE="$CONTRACT_FILE" ENTRY_FILE="$ENTRY_FILE" $PYTHON_CMD -c "
+import json, os
 
-with open('$CONTRACT_FILE') as f:
+with open(os.environ['CONTRACT_FILE']) as f:
   contract = json.load(f)
 
-with open('/tmp/opencode-adr-entry.json') as f:
+with open(os.environ['ENTRY_FILE']) as f:
   entry = json.load(f)
 
 if 'decisions' not in contract:
@@ -139,12 +133,14 @@ if 'adr_log' not in contract['decisions']:
 
 contract['decisions']['adr_log'].append(entry)
 
-with open('$CONTRACT_FILE', 'w') as f:
+with open(os.environ['CONTRACT_FILE'], 'w') as f:
   json.dump(contract, f, indent=2)
 
 print(json.dumps(entry, indent=2))
 "
 
+rm -f "$ENTRY_FILE"
+
 echo ""
 echo -e "${GREEN}[opencode-kit] ✅ ADR recorded: $NEXT_ID${NC}"
 echo "  Title:        $TITLE"

package/src/cli.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 /**
- * opencode-kit CLI — version and help
+ * opencode-kit CLI — version, help, and project commands
  * Usage: npx opencode-kit --version
  *        npx opencode-kit --help
+ *        npx opencode-kit doctor
+ *        npx opencode-kit status
+ *        npx opencode-kit analytics
  */
 import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
+import { spawnSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkgPath = path.resolve(__dirname, '../package.json');
@@ -27,10 +31,13 @@ Usage:
   npx opencode-kit [command]
 
 Commands:
-  init [--force]    Scaffold orchestration framework into project
-  update [--dry-run] Pull latest templates from GitHub
-  --version, -v     Print version
-  --help, -h        Print this help
+  init [--force]         Scaffold orchestration framework into project
+  update [--dry-run]     Pull latest templates from GitHub
+  doctor                 Run project health checks
+  status                 Show project status
+  analytics              Show project analytics
+  --version, -v          Print version
+  --help, -h             Print this help
 
 Plugin mode:
   Add "opencode-kit" to opencode.json plugin array (FIRST position).
@@ -45,3 +52,38 @@ Docs: ${pkg.homepage}
 `);
   process.exit(0);
 }
+
+/**
+ * Walk up from startDir to find a directory containing .opencode/
+ */
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.opencode'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+const commands = {
+  doctor: '.opencode/src/doctor.sh',
+  status: '.opencode/src/status.sh',
+  analytics: 'src/analytics.sh',
+};
+
+const command = args[0];
+
+if (commands[command]) {
+  const projectRoot = findProjectRoot(path.resolve(__dirname, '..'));
+
+  if (!projectRoot) {
+    console.error('Not in an opencode-kit project');
+    process.exit(1);
+  }
+
+  const scriptPath = path.resolve(projectRoot, commands[command]);
+  const result = spawnSync('bash', [scriptPath], { stdio: 'inherit', cwd: projectRoot });
+  process.exit(result.status);
+}

package/src/diff.sh

@@ -42,13 +42,25 @@ if [ -z "$CONTRACT_A" ] && [ -z "$CONTRACT_B" ]; then
 fi
 
 # Show state diff
+# Write contract data to temp files for safe Python consumption
+CONTRACT_A_FILE=$(mktemp /tmp/opencode-diff-a-XXXXXX.json 2>/dev/null || mktemp /tmp/opencode-diff-a-XXXXXX)
+CONTRACT_B_FILE=$(mktemp /tmp/opencode-diff-b-XXXXXX.json 2>/dev/null || mktemp /tmp/opencode-diff-b-XXXXXX)
+trap 'rm -f "$CONTRACT_A_FILE" "$CONTRACT_B_FILE"' EXIT INT TERM
+
+echo "$CONTRACT_A" > "$CONTRACT_A_FILE"
+echo "$CONTRACT_B" > "$CONTRACT_B_FILE"
+
 if [ -n "$PYTHON_CMD" ]; then
   $PYTHON_CMD -c "
 import json, sys
 
-def get_state(c):
+def get_state(filepath):
     try:
-        d = json.loads(c)
+        with open(filepath) as f:
+            content = f.read().strip()
+        if not content:
+            return None
+        d = json.loads(content)
         return {
             'state': d.get('state', '?'),
             'goal': (d.get('requirements', {}) or {}).get('goal', '?'),
@@ -60,12 +72,12 @@ def get_state(c):
     except:
         return None
 
-a = get_state('''$CONTRACT_A''') if '''$CONTRACT_A''' else None
-b = get_state('''$CONTRACT_B''') if '''$CONTRACT_B''' else None
+a = get_state('$CONTRACT_A_FILE')
+b = get_state('$CONTRACT_B_FILE')
 
 if a and b:
     print(f'  Field                   $BRANCH_A          $BRANCH_B')
-    print(f'  {"-"*50}')
+    print(f'  {\"-\"*50}')
     for field in ['state', 'goal', 'score', 'version']:
         va = str(a.get(field, '?'))[:20]
         vb = str(b.get(field, '?'))[:20]
@@ -80,6 +92,8 @@ elif b and not a:
     print(f'  Contract exists in $BRANCH_B but NOT in $BRANCH_A')
     print(f'  State: {b.get(\"state\",\"?\")}')
 " 2>/dev/null || echo -e "${YELLOW}Could not parse contract JSON${NC}"
+
+rm -f "$CONTRACT_A_FILE" "$CONTRACT_B_FILE"
 fi
 
 # Raw git diff

package/src/doctor.sh

@@ -42,6 +42,32 @@ else
   fi
 fi
 
+# === 1b. Contract schema validation ===
+SCHEMA_FILE=".opencode/templates/contract.schema.json"
+if [ -f "$CONTRACT_FILE" ] && [ -f "$SCHEMA_FILE" ] && [ -n "$PYTHON_CMD" ]; then
+  if $PYTHON_CMD -c "
+import json, sys
+with open('$CONTRACT_FILE') as f: contract = json.load(f)
+with open('$SCHEMA_FILE') as f: schema = json.load(f)
+# Basic required-field validation
+errors = []
+if not contract.get('state'): errors.append('Missing state')
+if not contract.get('requirements', {}).get('goal'): errors.append('Missing requirements.goal')
+if contract.get('state') not in ['INIT','PLAN','PLAN_SCORED','EXECUTE','EXECUTE_SCORED','REVIEW','REVIEW_SCORED','COMPLETE','BLOCKED']:
+  errors.append('Invalid state')
+if errors:
+  print('; '.join(errors))
+  sys.exit(1)
+else:
+  print('OK')
+" 2>/dev/null; then
+    echo -e "  ✅ Contract schema valid"
+  else
+    echo -e "  ⚠️  Contract schema issues found (non-blocking)"
+    ISSUES=$((ISSUES + 1))
+  fi
+fi
+
 # === 2. Rules check ===
 echo -e "${CYAN}[RULES]${NC} Checking rules.json..."
 if [ ! -f "$RULES_FILE" ]; then
@@ -54,7 +80,7 @@ else
   fi
 fi
 
-# === 3. MCP checks ===
+# === 3a. MCP CLI checks ===
 echo -e "${CYAN}[MCP]${NC} Checking required MCPs..."
 if [ -f "$RULES_FILE" ] && [ -n "$PYTHON_CMD" ]; then
   $PYTHON_CMD -c "
@@ -78,6 +104,16 @@ for name, cfg in mcps.items():
 " 2>/dev/null || ISSUES=$((ISSUES + 1))
 fi
 
+# === 3b. MCP connectivity ===
+echo -e "${CYAN}[MCP_CONNECT]${NC} Testing MCP connectivity..."
+if command -v lean-ctx &>/dev/null; then
+  if lean-ctx ctx_knowledge status &>/dev/null 2>&1; then
+    echo -e "  ✅ lean-ctx MCP: responding"
+  else
+    echo -e "  ⚠️  lean-ctx CLI found but MCP not responding (expected in CI)"
+  fi
+fi
+
 # === 4. Git branch ===
 echo -e "${CYAN}[GIT]${NC} Checking branch..."
 BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")

package/src/init.sh

@@ -83,8 +83,8 @@ if [ -d ".opencode" ]; then
     echo "  ✅ Backed up to $BACKUP"
   else
     echo ""
-    echo -e "${YELLOW}⚠️  .opencode/ already exists. Use --force to overwrite (backup + clean scaffold).${NC}"
-    echo "  Missing files will be added. Existing files will NOT be overwritten."
+    echo -e "${YELLOW}⚠️  .opencode/ already exists. Use --force to re-scaffold (backup + clean).${NC}"
+    echo "  Skipping — existing .opencode/ preserved."
   fi
 fi
 
@@ -168,6 +168,13 @@ if [ "$PLUGIN_MODE" = false ]; then
   done
 fi
 
+# --- Copy git hooks ---
+if [ -d "$KIT_DIR/.githooks" ]; then
+  cp -r "$KIT_DIR/.githooks" .githooks
+  chmod +x .githooks/pre-commit .githooks/commit-msg
+  echo "  ✅ .githooks/ (pre-commit, commit-msg)"
+fi
+
 # --- Git ignore .opencode/src (scripts are project-specific) ---
 if [ -f ".gitignore" ]; then
   if ! grep -q ".opencode/src" .gitignore 2>/dev/null; then
@@ -175,6 +182,12 @@ if [ -f ".gitignore" ]; then
   fi
 fi
 
+# --- Configure git hooks ---
+if [ -d ".githooks" ]; then
+  git config core.hooksPath .githooks
+  echo "  ✅ Git hooks configured (.githooks/)"
+fi
+
 # --- Verify ---
 echo ""
 echo "[opencode-kit] Running verification..."