@t3lnet/sceneforge 1.0.34 → 1.0.35

package/context/context-builder.ts

@@ -113,6 +113,12 @@ async function writeSplitPointer(
   outputDir: string
 ): Promise<{ filePath: string; merged: boolean }> {
   const config = getToolConfig(tool);
+
+  // Base reference file
+  const baseFile = `${config.splitFilePrefix}base${config.fileExtension}`;
+  const baseRelativePath = path.posix.join(config.splitDir, baseFile);
+
+  // Stage files
   const stageLines = stageNames.map((stage) => {
     const friendly = formatStageName(stage);
     const stageFile = `${config.splitFilePrefix}${getStageFileName(stage)}${config.fileExtension}`;
@@ -121,11 +127,17 @@ async function writeSplitPointer(
   });
 
   const pointerBody = [
-    "SceneForge context for this tool is split across the following stage files:",
+    "SceneForge context for this tool is split into modular files:",
     "",
+    "**Reference Documentation:**",
+    `- Base Reference (YAML schema, CLI, selectors): ${baseRelativePath}`,
+    "",
+    "**Stage-Specific Instructions:**",
     ...stageLines,
     "",
-    `Open the stage file that matches the work you're doing, or run "npx sceneforge context preview --target ${tool} --stage <stage>" to inspect a specific stage.`,
+    `Open the stage file that matches the work you're doing. The base reference contains shared documentation used across all stages.`,
+    "",
+    `Run "npx sceneforge context preview --target ${tool} --stage <stage>" to inspect a specific stage.`,
   ].join("\n");
 
   const formattedPointer = formatForTool(tool, pointerBody, {
@@ -145,6 +157,8 @@ async function writeSplitPointer(
 
 /**
  * Build context content for a specific tool and stage.
+ * For combined format, includes both base and stage templates.
+ * For split format, use buildBaseContext and buildStageOnlyContext instead.
  */
 export async function buildContext(
   tool: TargetTool,
@@ -187,6 +201,58 @@ export async function buildContext(
   return formatForTool(tool, content, { stage: stageName });
 }
 
+/**
+ * Build base context content only (for split format).
+ * Contains reference documentation shared across all stages.
+ */
+export async function buildBaseContext(
+  tool: TargetTool,
+  variables?: TemplateVariables
+): Promise<string> {
+  const baseTemplates = await loadTemplatesByCategory("base");
+
+  let content = composeTemplates(baseTemplates, {
+    separator: "\n\n---\n\n",
+    includeHeaders: false,
+  });
+
+  if (variables) {
+    content = interpolateVariables(content, variables);
+  }
+
+  return formatForTool(tool, content, { stage: "Base Reference" });
+}
+
+/**
+ * Build stage-only context content (for split format).
+ * Contains only stage-specific instructions without base templates.
+ */
+export async function buildStageOnlyContext(
+  tool: TargetTool,
+  stage: Stage,
+  variables?: TemplateVariables
+): Promise<string> {
+  if (stage === "all") {
+    throw new Error("buildStageOnlyContext does not support 'all' stage");
+  }
+
+  const stageFileName = getStageFileName(stage);
+  const stageTemplate = await loadTemplate("stages", stageFileName);
+
+  let content = stageTemplate.content;
+
+  if (variables) {
+    content = interpolateVariables(content, variables);
+  }
+
+  // Add a note pointing to base reference
+  const baseNote = `> **Note:** This file contains stage-specific instructions. See \`base.md\` in this directory for reference documentation (YAML schema, CLI commands, selectors guide, etc.).\n\n`;
+
+  return formatForTool(tool, baseNote + content, {
+    stage: formatStageName(stage),
+  });
+}
+
 /**
  * Deploy context files to the target directory.
  */
@@ -245,11 +311,58 @@ export async function deployContext(
         });
       }
     } else {
-      // Generate split files for each stage
+      // Generate split files: one base file + individual stage files
+      const config = getToolConfig(tool);
+
+      // First, deploy the base reference file
+      try {
+        const baseContent = await buildBaseContext(tool, variables);
+        const baseFilePath = path.join(
+          outputDir,
+          config.splitDir,
+          `${config.splitFilePrefix}base${config.fileExtension}`
+        );
+        const absoluteBasePath = path.resolve(baseFilePath);
+
+        await fs.mkdir(path.dirname(absoluteBasePath), { recursive: true });
+
+        const { content: finalBaseContent, merged: baseMerged } =
+          await mergeWithExisting(absoluteBasePath, baseContent);
+
+        await fs.writeFile(absoluteBasePath, finalBaseContent, "utf-8");
+
+        results.push({
+          tool,
+          filePath: absoluteBasePath,
+          stage: "base",
+          created: true,
+          skipped: false,
+        });
+
+        if (baseMerged) {
+          console.log(
+            `  [merged] ${path.relative(outputDir, absoluteBasePath)}`
+          );
+        }
+      } catch (error) {
+        results.push({
+          tool,
+          filePath: path.join(
+            outputDir,
+            config.splitDir,
+            `${config.splitFilePrefix}base${config.fileExtension}`
+          ),
+          stage: "base",
+          created: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      // Then deploy individual stage files (without base content)
       const deployedStages: Stage[] = [];
       for (const stg of stages) {
         try {
-          const content = await buildContext(tool, stg, variables);
+          const content = await buildStageOnlyContext(tool, stg, variables);
           const stageName = getStageFileName(stg);
           const filePath = getOutputPath(tool, format, outputDir, stageName);
           const absolutePath = path.resolve(filePath);

package/context/index.ts

@@ -38,6 +38,8 @@ export {
 // Context builder
 export {
   buildContext,
+  buildBaseContext,
+  buildStageOnlyContext,
   deployContext,
   previewContext,
   listDeployedContext,

package/context/tests/context-builder.test.ts

@@ -118,12 +118,14 @@ describe("context-builder", () => {
         outputDir: tempDir,
       });
 
-      expect(results.length).toBe(2);
-      expect(results[0].created).toBe(true);
+      // Split format now creates: base.md + stage file + pointer file
+      expect(results.length).toBe(3);
+      expect(results.every((r) => r.created)).toBe(true);
 
       const splitDir = path.join(tempDir, ".claude/rules");
       const files = await fs.readdir(splitDir);
-      expect(files.length).toBeGreaterThan(0);
+      expect(files).toContain("base.md");
+      expect(files).toContain("stage1-actions.md");
     });
 
     it("deploys multiple stages in split format", async () => {
@@ -134,7 +136,8 @@ describe("context-builder", () => {
         outputDir: tempDir,
       });
 
-      expect(results.length).toBe(5);
+      // Split format now creates: base.md + 4 stage files + pointer file = 6
+      expect(results.length).toBe(6);
       expect(results.every((r) => r.created)).toBe(true);
     });
 
@@ -147,7 +150,8 @@ describe("context-builder", () => {
       });
 
       const claudeFile = await fs.readFile(path.join(tempDir, "CLAUDE.md"), "utf-8");
-      expect(claudeFile).toContain("split across the following stage files");
+      expect(claudeFile).toContain("split into modular files");
+      expect(claudeFile).toContain("Base Reference");
       expect(claudeFile).toContain(".claude/rules/stage1-actions.md");
     });
   });

package/dist/index.cjs

@@ -2728,6 +2728,8 @@ async function mergeWithExisting(filePath, newContent) {
 }
 async function writeSplitPointer(tool, stageNames, outputDir) {
   const config = getToolConfig(tool);
+  const baseFile = `${config.splitFilePrefix}base${config.fileExtension}`;
+  const baseRelativePath = path6.posix.join(config.splitDir, baseFile);
   const stageLines = stageNames.map((stage) => {
     const friendly = formatStageName(stage);
     const stageFile = `${config.splitFilePrefix}${getStageFileName(stage)}${config.fileExtension}`;
@@ -2735,11 +2737,17 @@ async function writeSplitPointer(tool, stageNames, outputDir) {
     return `- ${friendly}: ${relativePath}`;
   });
   const pointerBody = [
-    "SceneForge context for this tool is split across the following stage files:",
+    "SceneForge context for this tool is split into modular files:",
     "",
+    "**Reference Documentation:**",
+    `- Base Reference (YAML schema, CLI, selectors): ${baseRelativePath}`,
+    "",
+    "**Stage-Specific Instructions:**",
     ...stageLines,
     "",
-    `Open the stage file that matches the work you're doing, or run "npx sceneforge context preview --target ${tool} --stage <stage>" to inspect a specific stage.`
+    `Open the stage file that matches the work you're doing. The base reference contains shared documentation used across all stages.`,
+    "",
+    `Run "npx sceneforge context preview --target ${tool} --stage <stage>" to inspect a specific stage.`
   ].join("\n");
   const formattedPointer = formatForTool(tool, pointerBody, {
     includeToolHeader: true
@@ -2778,6 +2786,34 @@ async function buildContext(tool, stage, variables) {
   const stageName = stage === "all" ? void 0 : formatStageName(stage);
   return formatForTool(tool, content, { stage: stageName });
 }
+async function buildBaseContext(tool, variables) {
+  const baseTemplates = await loadTemplatesByCategory("base");
+  let content = composeTemplates(baseTemplates, {
+    separator: "\n\n---\n\n",
+    includeHeaders: false
+  });
+  if (variables) {
+    content = interpolateVariables(content, variables);
+  }
+  return formatForTool(tool, content, { stage: "Base Reference" });
+}
+async function buildStageOnlyContext(tool, stage, variables) {
+  if (stage === "all") {
+    throw new Error("buildStageOnlyContext does not support 'all' stage");
+  }
+  const stageFileName = getStageFileName(stage);
+  const stageTemplate = await loadTemplate("stages", stageFileName);
+  let content = stageTemplate.content;
+  if (variables) {
+    content = interpolateVariables(content, variables);
+  }
+  const baseNote = `> **Note:** This file contains stage-specific instructions. See \`base.md\` in this directory for reference documentation (YAML schema, CLI commands, selectors guide, etc.).
+
+`;
+  return formatForTool(tool, baseNote + content, {
+    stage: formatStageName(stage)
+  });
+}
 async function deployContext(options) {
   const { target, stage, format, outputDir, variables } = options;
   const results = [];
@@ -2813,10 +2849,47 @@ async function deployContext(options) {
         });
       }
     } else {
+      const config = getToolConfig(tool);
+      try {
+        const baseContent = await buildBaseContext(tool, variables);
+        const baseFilePath = path6.join(
+          outputDir,
+          config.splitDir,
+          `${config.splitFilePrefix}base${config.fileExtension}`
+        );
+        const absoluteBasePath = path6.resolve(baseFilePath);
+        await fs6.mkdir(path6.dirname(absoluteBasePath), { recursive: true });
+        const { content: finalBaseContent, merged: baseMerged } = await mergeWithExisting(absoluteBasePath, baseContent);
+        await fs6.writeFile(absoluteBasePath, finalBaseContent, "utf-8");
+        results.push({
+          tool,
+          filePath: absoluteBasePath,
+          stage: "base",
+          created: true,
+          skipped: false
+        });
+        if (baseMerged) {
+          console.log(
+            `  [merged] ${path6.relative(outputDir, absoluteBasePath)}`
+          );
+        }
+      } catch (error) {
+        results.push({
+          tool,
+          filePath: path6.join(
+            outputDir,
+            config.splitDir,
+            `${config.splitFilePrefix}base${config.fileExtension}`
+          ),
+          stage: "base",
+          created: false,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
       const deployedStages = [];
       for (const stg of stages) {
         try {
-          const content = await buildContext(tool, stg, variables);
+          const content = await buildStageOnlyContext(tool, stg, variables);
           const stageName = getStageFileName(stg);
           const filePath = getOutputPath(tool, format, outputDir, stageName);
           const absolutePath = path6.resolve(filePath);