forge-orkes 0.3.5 → 0.3.6

package/bin/create-forge.js

@@ -8,6 +8,11 @@ const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
 const pkgVersion = require('../package.json').version;
 
+// --- Section markers for CLAUDE.md ---
+
+const FORGE_START = '<!-- forge:start -->';
+const FORGE_END = '<!-- forge:end -->';
+
 // --- File classification for upgrades ---
 
 // Framework-owned: Forge controls these entirely
@@ -16,9 +21,6 @@ const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 // Template-only: reference templates Forge controls
 const TEMPLATE_ONLY_DIRS = ['.forge/templates'];
 
-// Merge-owned: never auto-overwrite, stage for review
-const MERGE_OWNED_FILES = ['CLAUDE.md'];
-
 // Settings file gets smart-merge (overwrite forge.* keys, preserve user hooks)
 const SETTINGS_FILE = '.claude/settings.json';
 
@@ -128,27 +130,62 @@ function upgradeDir(relDir) {
 }
 
 /**
- * Handle merge-owned files: stage new version for manual review if different.
+ * Smart-merge CLAUDE.md using section markers.
+ * - If markers exist: replace the forge section, preserve everything else
+ * - If no markers but forge content exists: replace it and add markers
+ * - If no forge content: append with markers
+ * Returns 'replaced' | 'appended' | 'unchanged' | 'created'
  */
-function handleMergeFile(relFile) {
-  const srcPath = path.join(templateDir, relFile);
-  const destPath = path.join(targetDir, relFile);
+function mergeClaudeMd() {
+  const srcPath = path.join(templateDir, 'CLAUDE.md');
+  const destPath = path.join(targetDir, 'CLAUDE.md');
 
   if (!fs.existsSync(srcPath)) return null;
-  if (!fs.existsSync(destPath)) return null;
 
-  const srcContent = fs.readFileSync(srcPath, 'utf-8');
-  const destContent = fs.readFileSync(destPath, 'utf-8');
+  const forgeContent = fs.readFileSync(srcPath, 'utf-8');
+
+  // No existing CLAUDE.md — just copy
+  if (!fs.existsSync(destPath)) {
+    fs.writeFileSync(destPath, forgeContent);
+    return 'created';
+  }
+
+  const existing = fs.readFileSync(destPath, 'utf-8');
 
-  if (srcContent === destContent) return 'unchanged';
+  // Check if content is already identical
+  if (existing === forgeContent) return 'unchanged';
 
-  // Stage the new version for manual review
-  const upgradeDir = path.join(targetDir, '.forge', 'upgrade');
-  fs.mkdirSync(upgradeDir, { recursive: true });
-  const basename = path.basename(relFile);
-  const newPath = path.join(upgradeDir, `${basename}.new`);
-  fs.writeFileSync(newPath, srcContent);
-  return 'staged';
+  const startIdx = existing.indexOf(FORGE_START);
+  const endIdx = existing.indexOf(FORGE_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    // Markers found — replace the section between them (inclusive)
+    const before = existing.substring(0, startIdx);
+    const after = existing.substring(endIdx + FORGE_END.length);
+    const merged = before + forgeContent + after;
+
+    // Clean up any double newlines at the seams
+    const cleaned = merged.replace(/\n{3,}/g, '\n\n');
+    fs.writeFileSync(destPath, cleaned);
+    return 'replaced';
+  }
+
+  // No markers — check if there's an old forge section (starts with "# Forge")
+  const forgeHeaderIdx = existing.indexOf('# Forge\n');
+  if (forgeHeaderIdx !== -1) {
+    // Old install without markers — replace from "# Forge" to end of file
+    // (Forge content is always appended at the end in old installs)
+    const before = existing.substring(0, forgeHeaderIdx);
+    const merged = before + forgeContent;
+    const cleaned = merged.replace(/\n{3,}/g, '\n\n');
+    fs.writeFileSync(destPath, cleaned);
+    return 'replaced';
+  }
+
+  // No forge content at all — append with markers
+  const merged = existing.trimEnd() + '\n\n' + forgeContent + '\n';
+  fs.writeFileSync(destPath, merged);
+  return 'appended';
 }
 
 /**
@@ -178,49 +215,40 @@ function upgradeSettings() {
   return 'updated';
 }
 
+/**
+ * Detect if Forge is already installed in this project.
+ */
+function isForgeInstalled() {
+  const settingsPath = path.join(targetDir, SETTINGS_FILE);
+  if (!fs.existsSync(settingsPath)) return false;
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    return !!settings.forge;
+  } catch {
+    return false;
+  }
+}
+
 // --- Commands ---
 
 async function install() {
   console.log('\n  Forge - Meta-prompting framework for Claude Code\n');
 
-  // Handle CLAUDE.md
-  const srcClaudeMd = path.join(templateDir, 'CLAUDE.md');
-  const destClaudeMd = path.join(targetDir, 'CLAUDE.md');
-  let claudeMdAction = 'copy';
-
-  if (fs.existsSync(destClaudeMd)) {
-    console.log('  CLAUDE.md already exists in this directory.\n');
-    const answer = await prompt(
-      '  What would you like to do? (a)ppend / (r)eplace / (s)kip: '
-    );
-
-    if (answer === 'a' || answer === 'append') {
-      claudeMdAction = 'append';
-    } else if (answer === 'r' || answer === 'replace') {
-      claudeMdAction = 'replace';
-    } else {
-      claudeMdAction = 'skip';
-    }
-  }
-
-  const srcContent = fs.readFileSync(srcClaudeMd, 'utf-8');
-
-  switch (claudeMdAction) {
-    case 'copy':
-    case 'replace':
-      fs.writeFileSync(destClaudeMd, srcContent);
-      console.log(
-        `  ${claudeMdAction === 'replace' ? 'Replaced' : 'Created'} CLAUDE.md`
-      );
+  // Handle CLAUDE.md — use smart merge
+  const claudeStatus = mergeClaudeMd();
+  switch (claudeStatus) {
+    case 'created':
+      console.log('  Created CLAUDE.md');
+      break;
+    case 'replaced':
+      console.log('  Updated Forge section in CLAUDE.md (user content preserved)');
       break;
-    case 'append': {
-      const existing = fs.readFileSync(destClaudeMd, 'utf-8');
-      fs.writeFileSync(destClaudeMd, existing + '\n\n' + srcContent);
+    case 'appended':
       console.log('  Appended Forge config to existing CLAUDE.md');
       break;
-    }
-    case 'skip':
-      console.log('  Skipped CLAUDE.md');
+    case 'unchanged':
+      console.log('  CLAUDE.md already up to date');
       break;
   }
 
@@ -274,7 +302,6 @@ async function upgrade() {
     added: [],
     unchanged: [],
     removed: [],
-    needsReview: [],
   };
 
   // 1. Process framework-owned directories
@@ -295,14 +322,14 @@ async function upgrade() {
     results.removed.push(...dirResult.removed);
   }
 
-  // 3. Process merge-owned files
-  for (const file of MERGE_OWNED_FILES) {
-    const status = handleMergeFile(file);
-    if (status === 'staged') {
-      results.needsReview.push(file);
-    } else if (status === 'unchanged') {
-      results.unchanged.push(file);
-    }
+  // 3. Smart-merge CLAUDE.md using section markers
+  const claudeStatus = mergeClaudeMd();
+  if (claudeStatus === 'replaced' || claudeStatus === 'appended') {
+    results.updated.push('CLAUDE.md');
+  } else if (claudeStatus === 'unchanged') {
+    results.unchanged.push('CLAUDE.md');
+  } else if (claudeStatus === 'created') {
+    results.added.push('CLAUDE.md');
   }
 
   // 4. Smart-merge settings.json
@@ -314,8 +341,7 @@ async function upgrade() {
   }
 
   // Report results
-  const totalChanges =
-    results.updated.length + results.added.length + results.needsReview.length;
+  const totalChanges = results.updated.length + results.added.length;
 
   if (totalChanges === 0 && results.removed.length === 0) {
     console.log('  Already up to date.\n');
@@ -338,14 +364,6 @@ async function upgrade() {
     console.log();
   }
 
-  if (results.needsReview.length > 0) {
-    console.log(`  Needs manual review (${results.needsReview.length}):`);
-    for (const f of results.needsReview) {
-      console.log(`    ${f} → .forge/upgrade/${path.basename(f)}.new`);
-    }
-    console.log();
-  }
-
   if (results.removed.length > 0) {
     console.log(`  Removed from template (${results.removed.length}):`);
     for (const f of results.removed) {
@@ -366,6 +384,13 @@ if (subcommand === 'upgrade') {
     console.error('Error:', err.message);
     process.exit(1);
   });
+} else if (isForgeInstalled()) {
+  // Auto-detect: Forge already installed, run upgrade instead
+  console.log('  Forge detected — running upgrade automatically.\n');
+  upgrade().catch((err) => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
 } else {
   install().catch((err) => {
     console.error('Error:', err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/CLAUDE.md

@@ -1,3 +1,4 @@
+<!-- forge:start -->
 # Forge
 
 A lean meta-prompting framework for Claude Code. Synthesizes context engineering (GSD) and constitutional governance (Spec-Kit) on Claude Code's native primitives.
@@ -161,3 +162,4 @@ Every task gets its own commit. Format: `{type}({scope}): {description}`
 Types: `feat`, `fix`, `test`, `refactor`, `chore`, `docs`
 Scope: phase-plan or feature area
 Never use `git add .` or `git add -A` — stage files individually.
+<!-- forge:end -->