ronin-skillforce 0.1.0 → 0.2.0-beta.0

package/bin/platforms/cursor.js

@@ -1,7 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { substituteTokens } from './_shared.js';
+import {
+  substituteTokens,
+  createInstallRun,
+  writeManagedFile,
+  printInstallSummary,
+} from './_shared.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PLUGIN_DIR = join(__dirname, '..', '..');
@@ -15,29 +20,27 @@ export function detect() {
 export async function install(scope = 'local') {
   const base = scope === 'global' ? (process.env.HOME || '') : process.cwd();
   const rulesDir = join(base, '.cursor', 'rules');
+  const run = createInstallRun();
+
   if (!existsSync(rulesDir)) {
     mkdirSync(rulesDir, { recursive: true });
     console.log('✓ Created .cursor/rules/ directory');
   }
 
-  const mdcPath = join(rulesDir, 'professor.mdc');
-  if (existsSync(mdcPath)) {
-    console.log('  ↔ .cursor/rules/professor.mdc (already exists)');
-  } else {
-    const frontmatterPath = join(PLUGIN_DIR, 'templates', 'cursor', 'professor.mdc');
-    const frontmatter = existsSync(frontmatterPath)
-      ? readFileSync(frontmatterPath, 'utf-8')
-      : '---\ndescription: Socratic learning assistant - professor mode\nalwaysApply: true\n---\n';
-    const rawSkill = readFileSync(join(PLUGIN_DIR, 'shared', 'SKILL.md'), 'utf-8');
-    // Strip YAML frontmatter from SKILL.md so the .mdc file has only one frontmatter block
-    const skill = rawSkill.startsWith('---')
-      ? rawSkill.replace(/^---[\s\S]*?---\n*/, '')
-      : rawSkill;
-    const combined = frontmatter + '\n' + skill;
-    const adapted = substituteTokens(combined, 'cursor');
-    writeFileSync(mdcPath, adapted);
-    console.log('  + .cursor/rules/professor.mdc');
-  }
+  const frontmatterPath = join(PLUGIN_DIR, 'templates', 'cursor', 'professor.mdc');
+  const frontmatter = existsSync(frontmatterPath)
+    ? readFileSync(frontmatterPath, 'utf-8')
+    : '---\ndescription: Socratic learning assistant - professor mode\nalwaysApply: true\n---\n';
+  const rawSkill = readFileSync(join(PLUGIN_DIR, 'shared', 'SKILL.md'), 'utf-8');
+  // Strip YAML frontmatter from SKILL.md so the .mdc file has only one frontmatter block
+  const skill = rawSkill.startsWith('---')
+    ? rawSkill.replace(/^---[\s\S]*?---\n*/, '')
+    : rawSkill;
+  const adapted = substituteTokens(`${frontmatter}\n${skill}`, 'cursor');
+
+  writeManagedFile(join(rulesDir, 'professor.mdc'), adapted, run, '.cursor/rules/professor.mdc');
+
+  printInstallSummary('Cursor', run);
 
   console.log(`
 ✅ Setup complete for Cursor!

package/bin/platforms/gemini.js

@@ -1,7 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { substituteTokens, generateCommandFiles } from './_shared.js';
+import {
+  substituteTokens,
+  generateCommandFiles,
+  createInstallRun,
+  writeManagedBlock,
+  printInstallSummary,
+} from './_shared.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PLUGIN_DIR = join(__dirname, '..', '..');
@@ -18,6 +24,8 @@ export function detect() {
 /** Install professor for Gemini CLI. scope = 'global' → ~/, 'local' → cwd/ */
 export async function install(scope = 'local') {
   const base = scope === 'global' ? (process.env.HOME || '') : process.cwd();
+  const run = createInstallRun();
+
   // 1. Create .gemini/ directory
   const geminiDir = join(base, '.gemini');
   if (!existsSync(geminiDir)) {
@@ -25,35 +33,26 @@ export async function install(scope = 'local') {
     console.log('✓ Created .gemini/ directory');
   }
 
-  // 2. Compile GEMINI.md from preamble + shared/SKILL.md, with ask_user substitution
+  // 2. Refresh the Professor block in GEMINI.md (preamble + shared/SKILL.md), ask_user substituted
   const preamblePath = join(PLUGIN_DIR, 'templates', 'gemini', 'GEMINI.md');
   const skillPath = join(PLUGIN_DIR, 'shared', 'SKILL.md');
   const preamble = existsSync(preamblePath) ? readFileSync(preamblePath, 'utf-8') : '';
   const skill = readFileSync(skillPath, 'utf-8');
-  const professorBlock =
-    `<!-- professor:start -->\n${preamble}\n${skill}\n<!-- professor:end -->`;
-  const adapted = substituteTokens(professorBlock, 'gemini');
+  const adapted = substituteTokens(`${preamble}\n${skill}`, 'gemini');
 
   // Global: GEMINI.md lives inside ~/.gemini/; local: GEMINI.md lives at cwd/ (Gemini CLI walks upward)
   const geminiMdPath = scope === 'global' ? join(geminiDir, 'GEMINI.md') : join(base, 'GEMINI.md');
-  if (existsSync(geminiMdPath)) {
-    const existing = readFileSync(geminiMdPath, 'utf-8');
-    if (existing.includes('<!-- professor:start -->')) {
-      console.log('  ↔ GEMINI.md (professor block already present, skipping)');
-    } else {
-      writeFileSync(geminiMdPath, existing + '\n\n' + adapted);
-      console.log('  + GEMINI.md (professor block appended to existing file)');
-    }
-  } else {
-    writeFileSync(geminiMdPath, adapted);
-    console.log('  + GEMINI.md');
-  }
+  const geminiLabel = scope === 'global' ? '~/.gemini/GEMINI.md' : 'GEMINI.md';
+  writeManagedBlock(geminiMdPath, adapted, run, geminiLabel);
 
   // 3. Generate .toml command files for Gemini CLI
+  console.log('✓ Generating command files...');
   const commandsDir = scope === 'global'
     ? join(geminiDir, 'commands', 'professor')
     : join(base, '.gemini', 'commands', 'professor');
-  generateCommandFiles(commandsDir, 'gemini');
+  generateCommandFiles(commandsDir, 'gemini', run);
+
+  printInstallSummary('Gemini CLI', run);
 
   console.log(`
 ✅ Setup complete for Gemini CLI!

package/bin/platforms/opencode.js

@@ -1,7 +1,18 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { substituteTokens, generateCommandFiles, adaptAgentFrontmatter } from './_shared.js';
+import {
+  substituteTokens,
+  generateCommandFiles,
+  adaptAgentFrontmatter,
+  createInstallRun,
+  writeManagedFile,
+  writeManagedBlock,
+  isLegacySkillDocument,
+  printInstallSummary,
+  BLOCK_START,
+  BLOCK_END,
+} from './_shared.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PLUGIN_DIR = join(__dirname, '..', '..');
@@ -25,51 +36,49 @@ export async function install(scope = 'local') {
     ? join(process.env.HOME || '', '.config', 'opencode')
     : join(process.cwd(), '.opencode');
 
+  const run = createInstallRun();
+
   if (!existsSync(configBase)) {
     mkdirSync(configBase, { recursive: true });
     console.log(`✓ Created ${scope === 'global' ? '~/.config/opencode/' : '.opencode/'} directory`);
   }
 
-  // 1. Write AGENTS.md (OpenCode auto-loads this — no config entry needed)
+  // 1. Refresh the Professor block in AGENTS.md (OpenCode auto-loads it — no config entry needed)
   const agentsMdPath = scope === 'global'
     ? join(configBase, 'AGENTS.md')
     : join(process.cwd(), 'AGENTS.md');
+  const agentsLabel = scope === 'global' ? '~/.config/opencode/AGENTS.md' : 'AGENTS.md';
+  const skillDoc = readFileSync(join(PLUGIN_DIR, 'shared', 'SKILL.md'), 'utf-8');
+  const skill = substituteTokens(skillDoc, 'opencode');
+
+  const existingAgentsMd = existsSync(agentsMdPath) ? readFileSync(agentsMdPath, 'utf-8') : null;
+  const isLegacyWholeFile = existingAgentsMd !== null
+    && !existingAgentsMd.includes(BLOCK_START)
+    && isLegacySkillDocument(existingAgentsMd);
 
-  if (!existsSync(agentsMdPath)) {
-    const skill = readFileSync(join(PLUGIN_DIR, 'shared', 'SKILL.md'), 'utf-8');
-    const adapted = substituteTokens(skill, 'opencode');
-    writeFileSync(agentsMdPath, adapted);
-    console.log(`  + ${scope === 'global' ? '~/.config/opencode/AGENTS.md' : 'AGENTS.md'}`);
+  if (isLegacyWholeFile) {
+    writeManagedFile(agentsMdPath, `${BLOCK_START}\n${skill}\n${BLOCK_END}\n`, run, agentsLabel);
   } else {
-    console.log(`  ↔ AGENTS.md (already exists)`);
+    writeManagedBlock(agentsMdPath, skill, run, agentsLabel);
   }
 
   // 2. Write command files into commands/ dir
+  console.log('✓ Generating command files...');
   const commandsDir = scope === 'global'
     ? join(configBase, 'commands')
     : join(process.cwd(), '.opencode', 'commands');
-
-  console.log('✓ Generating command files...');
-  generateCommandFiles(commandsDir, 'opencode');
+  generateCommandFiles(commandsDir, 'opencode', run);
 
   // 3. Write agents/professor.md
   const agentsDir = join(configBase, 'agents');
-  if (!existsSync(agentsDir)) {
-    mkdirSync(agentsDir, { recursive: true });
-  }
-  const agentFilePath = join(agentsDir, 'professor.md');
-  if (!existsSync(agentFilePath)) {
-    let agentSrc = readFileSync(join(PLUGIN_DIR, 'shared', 'agents', 'professor.md'), 'utf-8');
-    agentSrc = substituteTokens(agentSrc, 'opencode');
-    agentSrc = adaptAgentFrontmatter(agentSrc, 'opencode');
-    writeFileSync(agentFilePath, agentSrc);
-    const displayPath = scope === 'global' ? '~/.config/opencode/agents/professor.md' : '.opencode/agents/professor.md';
-    console.log(`  + ${displayPath}`);
-  } else {
-    console.log('  ↔ agents/professor.md (already exists)');
-  }
+  let agentSrc = readFileSync(join(PLUGIN_DIR, 'shared', 'agents', 'professor.md'), 'utf-8');
+  agentSrc = substituteTokens(agentSrc, 'opencode');
+  agentSrc = adaptAgentFrontmatter(agentSrc, 'opencode');
+  const displayPath = scope === 'global' ? '~/.config/opencode/agents/professor.md' : '.opencode/agents/professor.md';
+  writeManagedFile(join(agentsDir, 'professor.md'), agentSrc, run, displayPath);
 
-  // 4. Write opencode.json — $schema only, no instructions[] field
+  // 4. Merge opencode.json — $schema only, no instructions[] field. Not plugin-owned content,
+  // so it is counted but never backed up.
   const opencodeJsonPath = join(configBase, 'opencode.json');
   let config = {};
   if (existsSync(opencodeJsonPath)) {
@@ -81,9 +90,19 @@ export async function install(scope = 'local') {
 
   if (!config.$schema) config.$schema = 'https://opencode.ai/config.json';
 
-  writeFileSync(opencodeJsonPath, JSON.stringify(config, null, 2) + '\n');
   const configDisplayPath = scope === 'global' ? '~/.config/opencode/opencode.json' : '.opencode/opencode.json';
-  console.log(`  + ${configDisplayPath}`);
+  const json = JSON.stringify(config, null, 2) + '\n';
+  const previous = existsSync(opencodeJsonPath) ? readFileSync(opencodeJsonPath, 'utf-8') : null;
+  if (previous === json) {
+    run.unchanged++;
+    console.log(`  = ${configDisplayPath} (unchanged)`);
+  } else {
+    writeFileSync(opencodeJsonPath, json);
+    run.updated++;
+    console.log(`  ${previous === null ? '+' : '~'} ${configDisplayPath}`);
+  }
+
+  printInstallSummary('OpenCode', run);
 
   console.log(`
 ✅ Setup complete for OpenCode!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ronin-skillforce",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.0",
   "description": "Ronin SkillForce — a Socratic learning coach for AI agents and a local Studio. It teaches by asking questions, grounds lectures in real sources and keeps your progress on disk.",
   "type": "module",
   "bin": {
@@ -50,7 +50,8 @@
     "studio/src/lib/",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "keywords": [
     "learning",
@@ -81,8 +82,8 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "author": "ronnie-tk",
-  "license": "MIT",
+  "author": "Tuấn Khuất (ronnie)",
+  "license": "Apache-2.0",
   "packageManager": "npm@11.19.0",
   "devDependencies": {
     "@playwright/test": "^1.50.0",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "course-learning-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.0",
   "description": "A Socratic learning plugin for Claude Code. The professor agent guides learners through courses using the Socratic method — asking questions rather than giving answers.",
   "agents": [
     {