@t3lnet/sceneforge 1.0.12 → 1.0.14

package/context/context-builder.ts

@@ -27,6 +27,10 @@ import {
 
 export type Stage = "actions" | "scripts" | "balance" | "rebalance" | "all";
 
+// Markers for identifying SceneForge content in existing files
+const SCENEFORGE_START_MARKER = "<!-- SCENEFORGE_CONTEXT_START -->";
+const SCENEFORGE_END_MARKER = "<!-- SCENEFORGE_CONTEXT_END -->";
+
 export interface ContextBuilderOptions {
   target: TargetTool | "all";
   stage: Stage;
@@ -50,6 +54,59 @@ export interface PreviewResult {
   content: string;
 }
 
+/**
+ * Wrap content with SceneForge markers for identification.
+ */
+function wrapWithMarkers(content: string): string {
+  return `${SCENEFORGE_START_MARKER}\n${content}\n${SCENEFORGE_END_MARKER}`;
+}
+
+/**
+ * Merge SceneForge content into an existing file.
+ * - If file doesn't exist, returns wrapped content
+ * - If file exists without markers, appends wrapped content
+ * - If file exists with markers, replaces the marked section
+ */
+async function mergeWithExisting(
+  filePath: string,
+  newContent: string
+): Promise<{ content: string; merged: boolean }> {
+  const wrappedContent = wrapWithMarkers(newContent);
+
+  try {
+    const existingContent = await fs.readFile(filePath, "utf-8");
+
+    // Check if file already has SceneForge markers
+    const startIndex = existingContent.indexOf(SCENEFORGE_START_MARKER);
+    const endIndex = existingContent.indexOf(SCENEFORGE_END_MARKER);
+
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+      // Replace existing SceneForge section
+      const beforeSection = existingContent.slice(0, startIndex);
+      const afterSection = existingContent.slice(
+        endIndex + SCENEFORGE_END_MARKER.length
+      );
+      return {
+        content: beforeSection + wrappedContent + afterSection,
+        merged: true,
+      };
+    } else {
+      // Append SceneForge section to existing content
+      const separator = existingContent.trim().endsWith("-->") ? "\n\n" : "\n\n---\n\n";
+      return {
+        content: existingContent.trimEnd() + separator + wrappedContent + "\n",
+        merged: true,
+      };
+    }
+  } catch (error) {
+    // File doesn't exist, return wrapped content for new file
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { content: wrappedContent, merged: false };
+    }
+    throw error;
+  }
+}
+
 /**
  * Build context content for a specific tool and stage.
  */
@@ -124,14 +181,25 @@ export async function deployContext(
         // Ensure directory exists
         await fs.mkdir(path.dirname(absolutePath), { recursive: true });
 
+        // Merge with existing content or create new
+        const { content: finalContent, merged } = await mergeWithExisting(
+          absolutePath,
+          content
+        );
+
         // Write file
-        await fs.writeFile(absolutePath, content, "utf-8");
+        await fs.writeFile(absolutePath, finalContent, "utf-8");
 
         results.push({
           tool,
           filePath: absolutePath,
           created: true,
+          skipped: false,
         });
+
+        if (merged) {
+          console.log(`  [merged] ${path.relative(outputDir, absolutePath)}`);
+        }
       } catch (error) {
         results.push({
           tool,
@@ -152,15 +220,26 @@ export async function deployContext(
           // Ensure directory exists
           await fs.mkdir(path.dirname(absolutePath), { recursive: true });
 
+          // Merge with existing content or create new
+          const { content: finalContent, merged } = await mergeWithExisting(
+            absolutePath,
+            content
+          );
+
           // Write file
-          await fs.writeFile(absolutePath, content, "utf-8");
+          await fs.writeFile(absolutePath, finalContent, "utf-8");
 
           results.push({
             tool,
             filePath: absolutePath,
             stage: stg,
             created: true,
+            skipped: false,
           });
+
+          if (merged) {
+            console.log(`  [merged] ${path.relative(outputDir, absolutePath)}`);
+          }
         } catch (error) {
           results.push({
             tool,

package/context/template-loader.ts

@@ -3,6 +3,7 @@
  * Loads markdown templates and supports variable interpolation.
  */
 
+import { existsSync } from "fs";
 import * as fs from "fs/promises";
 import * as path from "path";
 import { fileURLToPath } from "url";
@@ -24,7 +25,22 @@ export interface LoadedTemplate {
  * Get the templates directory path.
  */
 function getTemplatesDir(): string {
-  return path.join(__dirname, "templates");
+  const candidates = [
+    // Standard dist layout: dist/templates/{base,stages,skills}
+    path.join(__dirname, "templates"),
+    // Nested layout if templates were copied into an existing dist/templates
+    path.join(__dirname, "templates", "templates"),
+    // Source layout when templates are shipped under context/templates
+    path.join(__dirname, "..", "context", "templates"),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(path.join(candidate, "base"))) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
 }
 
 /**
@@ -68,7 +84,9 @@ export async function loadTemplatesByCategory(
 
     return templates;
   } catch (error) {
-    throw new Error(`Failed to load templates from ${category}: ${error}`);
+    throw new Error(
+      `Failed to load templates from ${category} in ${templatesDir}: ${error}`
+    );
   }
 }
 

package/context/templates/base/cli-reference.md

@@ -182,12 +182,18 @@ sceneforge context <subcommand> [options]
 ```
 
 **Subcommands:**
-- `deploy` - Deploy context files
+- `deploy` - Deploy context files (additive - preserves existing content)
 - `list` - List deployed context
 - `remove` - Remove context files
 - `preview` - Preview context content
 - `skill` - Manage skills
 
+**Additive Deployment:**
+SceneForge uses markers to identify its content in instruction files:
+- `<!-- SCENEFORGE_CONTEXT_START -->` and `<!-- SCENEFORGE_CONTEXT_END -->`
+- Existing content outside these markers is preserved
+- Re-running deploy updates only the SceneForge section
+
 See dedicated context documentation for details.
 
 ## Output Structure

package/dist/index.cjs

@@ -2483,6 +2483,7 @@ async function discoverDemos(demoDir) {
 }
 
 // context/template-loader.ts
+var import_fs = require("fs");
 var fs5 = __toESM(require("fs/promises"), 1);
 var path5 = __toESM(require("path"), 1);
 var import_url = require("url");
@@ -2490,7 +2491,20 @@ var import_meta = {};
 var __filename = (0, import_url.fileURLToPath)(import_meta.url);
 var __dirname = path5.dirname(__filename);
 function getTemplatesDir() {
-  return path5.join(__dirname, "templates");
+  const candidates = [
+    // Standard dist layout: dist/templates/{base,stages,skills}
+    path5.join(__dirname, "templates"),
+    // Nested layout if templates were copied into an existing dist/templates
+    path5.join(__dirname, "templates", "templates"),
+    // Source layout when templates are shipped under context/templates
+    path5.join(__dirname, "..", "context", "templates")
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_fs.existsSync)(path5.join(candidate, "base"))) {
+      return candidate;
+    }
+  }
+  return candidates[0];
 }
 async function loadTemplate(category, name) {
   const templatesDir = getTemplatesDir();
@@ -2517,7 +2531,9 @@ async function loadTemplatesByCategory(category) {
     }
     return templates;
   } catch (error) {
-    throw new Error(`Failed to load templates from ${category}: ${error}`);
+    throw new Error(
+      `Failed to load templates from ${category} in ${templatesDir}: ${error}`
+    );
   }
 }
 function interpolateVariables(content, variables) {
@@ -2671,6 +2687,42 @@ function isValidFormat(format) {
 // context/context-builder.ts
 var fs6 = __toESM(require("fs/promises"), 1);
 var path6 = __toESM(require("path"), 1);
+var SCENEFORGE_START_MARKER = "<!-- SCENEFORGE_CONTEXT_START -->";
+var SCENEFORGE_END_MARKER = "<!-- SCENEFORGE_CONTEXT_END -->";
+function wrapWithMarkers(content) {
+  return `${SCENEFORGE_START_MARKER}
+${content}
+${SCENEFORGE_END_MARKER}`;
+}
+async function mergeWithExisting(filePath, newContent) {
+  const wrappedContent = wrapWithMarkers(newContent);
+  try {
+    const existingContent = await fs6.readFile(filePath, "utf-8");
+    const startIndex = existingContent.indexOf(SCENEFORGE_START_MARKER);
+    const endIndex = existingContent.indexOf(SCENEFORGE_END_MARKER);
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+      const beforeSection = existingContent.slice(0, startIndex);
+      const afterSection = existingContent.slice(
+        endIndex + SCENEFORGE_END_MARKER.length
+      );
+      return {
+        content: beforeSection + wrappedContent + afterSection,
+        merged: true
+      };
+    } else {
+      const separator = existingContent.trim().endsWith("-->") ? "\n\n" : "\n\n---\n\n";
+      return {
+        content: existingContent.trimEnd() + separator + wrappedContent + "\n",
+        merged: true
+      };
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { content: wrappedContent, merged: false };
+    }
+    throw error;
+  }
+}
 async function buildContext(tool, stage, variables) {
   const templates = [];
   const baseTemplates = await loadTemplatesByCategory("base");
@@ -2708,12 +2760,20 @@ async function deployContext(options) {
         const filePath = getOutputPath(tool, format, outputDir);
         const absolutePath = path6.resolve(filePath);
         await fs6.mkdir(path6.dirname(absolutePath), { recursive: true });
-        await fs6.writeFile(absolutePath, content, "utf-8");
+        const { content: finalContent, merged } = await mergeWithExisting(
+          absolutePath,
+          content
+        );
+        await fs6.writeFile(absolutePath, finalContent, "utf-8");
         results.push({
           tool,
           filePath: absolutePath,
-          created: true
+          created: true,
+          skipped: false
         });
+        if (merged) {
+          console.log(`  [merged] ${path6.relative(outputDir, absolutePath)}`);
+        }
       } catch (error) {
         results.push({
           tool,
@@ -2730,13 +2790,21 @@ async function deployContext(options) {
           const filePath = getOutputPath(tool, format, outputDir, stageName);
           const absolutePath = path6.resolve(filePath);
           await fs6.mkdir(path6.dirname(absolutePath), { recursive: true });
-          await fs6.writeFile(absolutePath, content, "utf-8");
+          const { content: finalContent, merged } = await mergeWithExisting(
+            absolutePath,
+            content
+          );
+          await fs6.writeFile(absolutePath, finalContent, "utf-8");
           results.push({
             tool,
             filePath: absolutePath,
             stage: stg,
-            created: true
+            created: true,
+            skipped: false
           });
+          if (merged) {
+            console.log(`  [merged] ${path6.relative(outputDir, absolutePath)}`);
+          }
         } catch (error) {
           results.push({
             tool,