prjct-cli 0.45.5 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.46.0] - 2026-01-30
+
+### Features
+
+- preserve user customizations during sync - PRJ-115 (#70)
+
+
+## [0.46.0] - 2026-01-30
+
+### Added
+
+- **Preserve user customizations during sync** (PRJ-115)
+  - Wrap custom content in `<!-- prjct:preserve -->` markers
+  - Content survives `p. sync` regeneration
+  - Supports named sections: `<!-- prjct:preserve:my-rules -->`
+  - Works with CLAUDE.md, .cursorrules, and all context files
+
+
 ## [0.45.5] - 2026-01-30
 
 ### Bug Fixes

package/core/__tests__/utils/preserve-sections.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  extractPreservedContent,
+  extractPreservedSections,
+  hasPreservedSections,
+  mergePreservedSections,
+  stripPreservedSections,
+  validatePreserveBlocks,
+  wrapInPreserveMarkers,
+} from '../../utils/preserve-sections'
+
+describe('preserve-sections', () => {
+  describe('extractPreservedSections', () => {
+    it('should extract a single preserved section', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+My custom content
+<!-- /prjct:preserve -->
+
+# Footer`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(1)
+      expect(sections[0].content).toContain('My custom content')
+    })
+
+    it('should extract multiple preserved sections', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+First section
+<!-- /prjct:preserve -->
+
+Some content
+
+<!-- prjct:preserve -->
+Second section
+<!-- /prjct:preserve -->`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(2)
+      expect(sections[0].content).toContain('First section')
+      expect(sections[1].content).toContain('Second section')
+    })
+
+    it('should handle named sections', () => {
+      const content = `<!-- prjct:preserve:custom-rules -->
+My rules
+<!-- /prjct:preserve -->`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(1)
+      expect(sections[0].id).toBe('custom-rules')
+    })
+
+    it('should return empty array when no preserved sections', () => {
+      const content = '# Just normal content'
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(0)
+    })
+
+    it('should ignore unclosed preserve blocks', () => {
+      const content = `<!-- prjct:preserve -->
+No closing tag here`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(0)
+    })
+  })
+
+  describe('extractPreservedContent', () => {
+    it('should extract inner content without markers', () => {
+      const content = `<!-- prjct:preserve -->
+My content
+<!-- /prjct:preserve -->`
+
+      const inner = extractPreservedContent(content)
+      expect(inner).toHaveLength(1)
+      expect(inner[0]).toBe('My content')
+    })
+  })
+
+  describe('hasPreservedSections', () => {
+    it('should return true when preserved sections exist', () => {
+      const content = '<!-- prjct:preserve -->content<!-- /prjct:preserve -->'
+      expect(hasPreservedSections(content)).toBe(true)
+    })
+
+    it('should return false when no preserved sections', () => {
+      const content = '# Normal markdown'
+      expect(hasPreservedSections(content)).toBe(false)
+    })
+  })
+
+  describe('mergePreservedSections', () => {
+    it('should append preserved sections to new content', () => {
+      const oldContent = `# Old Header
+
+<!-- prjct:preserve -->
+# My Rules
+- Use tabs
+<!-- /prjct:preserve -->`
+
+      const newContent = `# New Generated Content
+
+This is fresh.`
+
+      const merged = mergePreservedSections(newContent, oldContent)
+
+      expect(merged).toContain('# New Generated Content')
+      expect(merged).toContain('My Rules')
+      expect(merged).toContain('Use tabs')
+      expect(merged).toContain('prjct:preserve')
+    })
+
+    it('should return new content unchanged when no preserved sections', () => {
+      const oldContent = '# Old content without preserve markers'
+      const newContent = '# New content'
+
+      const merged = mergePreservedSections(newContent, oldContent)
+      expect(merged).toBe(newContent)
+    })
+
+    it('should preserve multiple sections', () => {
+      const oldContent = `<!-- prjct:preserve -->
+Section 1
+<!-- /prjct:preserve -->
+
+<!-- prjct:preserve -->
+Section 2
+<!-- /prjct:preserve -->`
+
+      const newContent = '# New'
+
+      const merged = mergePreservedSections(newContent, oldContent)
+      expect(merged).toContain('Section 1')
+      expect(merged).toContain('Section 2')
+    })
+  })
+
+  describe('wrapInPreserveMarkers', () => {
+    it('should wrap content with default markers', () => {
+      const content = 'My content'
+      const wrapped = wrapInPreserveMarkers(content)
+
+      expect(wrapped).toContain('<!-- prjct:preserve -->')
+      expect(wrapped).toContain('My content')
+      expect(wrapped).toContain('<!-- /prjct:preserve -->')
+    })
+
+    it('should wrap content with named markers', () => {
+      const content = 'My content'
+      const wrapped = wrapInPreserveMarkers(content, 'custom')
+
+      expect(wrapped).toContain('<!-- prjct:preserve:custom -->')
+    })
+  })
+
+  describe('stripPreservedSections', () => {
+    it('should remove preserved sections from content', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+Custom stuff
+<!-- /prjct:preserve -->
+
+# Footer`
+
+      const stripped = stripPreservedSections(content)
+      expect(stripped).toContain('# Header')
+      expect(stripped).toContain('# Footer')
+      expect(stripped).not.toContain('Custom stuff')
+      expect(stripped).not.toContain('prjct:preserve')
+    })
+
+    it('should return content unchanged when no preserved sections', () => {
+      const content = '# Normal content'
+      const stripped = stripPreservedSections(content)
+      expect(stripped).toBe(content)
+    })
+  })
+
+  describe('validatePreserveBlocks', () => {
+    it('should validate correct blocks', () => {
+      const content = `<!-- prjct:preserve -->
+Content
+<!-- /prjct:preserve -->`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(true)
+      expect(result.errors).toHaveLength(0)
+    })
+
+    it('should detect mismatched markers', () => {
+      const content = `<!-- prjct:preserve -->
+Content without closing`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should detect nested blocks', () => {
+      const content = `<!-- prjct:preserve -->
+<!-- prjct:preserve -->
+Nested
+<!-- /prjct:preserve -->
+<!-- /prjct:preserve -->`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(false)
+      expect(result.errors.some((e) => e.includes('Nested'))).toBe(true)
+    })
+  })
+})

package/core/ai-tools/generator.ts

@@ -7,6 +7,7 @@
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import { mergePreservedSections } from '../utils/preserve-sections'
 import { getFormatter, type ProjectContext } from './formatters'
 import { AI_TOOLS, type AIToolConfig, DEFAULT_AI_TOOLS, getAIToolConfig } from './registry'
 
@@ -71,7 +72,7 @@ async function generateForTool(
 
   try {
     // Generate content
-    const content = formatter(context, config)
+    let content = formatter(context, config)
 
     // Determine output path
     let outputPath: string
@@ -84,6 +85,14 @@ async function generateForTool(
     // Ensure directory exists
     await fs.mkdir(path.dirname(outputPath), { recursive: true })
 
+    // Read existing file to preserve user customizations
+    try {
+      const existingContent = await fs.readFile(outputPath, 'utf-8')
+      content = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
     // Write file
     await fs.writeFile(outputPath, content, 'utf-8')
 

package/core/services/context-generator.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import dateHelper from '../utils/date-helper'
+import { mergePreservedSections } from '../utils/preserve-sections'
 
 // ============================================================================
 // TYPES
@@ -180,7 +181,17 @@ Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
 **Domain**: ${domainAgents.join(', ') || 'none'}
 `
 
-    await fs.writeFile(path.join(contextPath, 'CLAUDE.md'), content, 'utf-8')
+    // Preserve user customizations from existing file
+    const claudePath = path.join(contextPath, 'CLAUDE.md')
+    let finalContent = content
+    try {
+      const existingContent = await fs.readFile(claudePath, 'utf-8')
+      finalContent = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
+    await fs.writeFile(claudePath, finalContent, 'utf-8')
   }
 
   /**

package/core/utils/preserve-sections.ts

@@ -0,0 +1,218 @@
+/**
+ * Preserve Sections Utility
+ *
+ * Extracts and preserves user-customized sections during file regeneration.
+ * Users can mark sections with preserve markers to survive sync.
+ *
+ * Usage in CLAUDE.md or other context files:
+ * ```markdown
+ * <!-- prjct:preserve -->
+ * # My Custom Rules
+ * - Always use tabs
+ * - Prefer functional patterns
+ * <!-- /prjct:preserve -->
+ * ```
+ *
+ * @see PRJ-115
+ * @module utils/preserve-sections
+ */
+
+export interface PreservedSection {
+  id: string
+  content: string
+  startIndex: number
+  endIndex: number
+}
+
+// Markers for preserved sections
+const PRESERVE_START = '<!-- prjct:preserve -->'
+const PRESERVE_END = '<!-- /prjct:preserve -->'
+const PRESERVE_END_PATTERN = '<!-- /prjct:preserve -->'
+
+// Named section markers (optional identifier) - create fresh regex each time
+// Uses [\w-]+ to allow hyphens in section names (e.g., "custom-rules")
+function createPreserveStartRegex(): RegExp {
+  return /<!-- prjct:preserve(?::([\w-]+))? -->/g
+}
+
+/**
+ * Extract all preserved sections from content
+ */
+export function extractPreservedSections(content: string): PreservedSection[] {
+  const sections: PreservedSection[] = []
+  const regex = createPreserveStartRegex()
+
+  let match: RegExpExecArray | null
+  let sectionIndex = 0
+
+  while ((match = regex.exec(content)) !== null) {
+    const startIndex = match.index
+    const startTag = match[0]
+    const sectionId = match[1] || `section-${sectionIndex++}`
+
+    // Find the closing tag
+    const endTagStart = content.indexOf(PRESERVE_END_PATTERN, startIndex + startTag.length)
+
+    if (endTagStart === -1) {
+      // No closing tag found - skip this section
+      continue
+    }
+
+    const endIndex = endTagStart + PRESERVE_END_PATTERN.length
+
+    // Extract the content between markers (including markers)
+    const fullContent = content.substring(startIndex, endIndex)
+
+    sections.push({
+      id: sectionId,
+      content: fullContent,
+      startIndex,
+      endIndex,
+    })
+  }
+
+  return sections
+}
+
+/**
+ * Extract the inner content of preserved sections (without markers)
+ */
+export function extractPreservedContent(content: string): string[] {
+  const sections = extractPreservedSections(content)
+
+  return sections.map((section) => {
+    // Remove the markers to get just the inner content
+    let inner = section.content
+    inner = inner.replace(createPreserveStartRegex(), '').replace(PRESERVE_END_PATTERN, '')
+    return inner.trim()
+  })
+}
+
+/**
+ * Check if content has any preserved sections
+ */
+export function hasPreservedSections(content: string): boolean {
+  return content.includes(PRESERVE_START) || createPreserveStartRegex().test(content)
+}
+
+/**
+ * Merge preserved sections from old content into new content
+ *
+ * Strategy:
+ * 1. Extract preserved sections from old content
+ * 2. Append them to the end of new content
+ * 3. Ensure proper spacing
+ *
+ * @param newContent - Freshly generated content
+ * @param oldContent - Previous content with user customizations
+ * @returns Merged content with preserved sections
+ */
+export function mergePreservedSections(newContent: string, oldContent: string): string {
+  const preservedSections = extractPreservedSections(oldContent)
+
+  if (preservedSections.length === 0) {
+    return newContent
+  }
+
+  // Build the merged content
+  let merged = newContent.trimEnd()
+
+  // Add separator before preserved sections
+  merged += '\n\n---\n\n'
+  merged += '## Your Customizations\n\n'
+  merged += '_The sections below are preserved during sync. Edit freely._\n\n'
+
+  // Append each preserved section
+  for (const section of preservedSections) {
+    merged += section.content
+    merged += '\n\n'
+  }
+
+  return merged.trimEnd() + '\n'
+}
+
+/**
+ * Create an empty preserve block for users to customize
+ */
+export function createEmptyPreserveBlock(title?: string): string {
+  const header = title ? `\n# ${title}\n` : '\n'
+  return `${PRESERVE_START}${header}<!-- Add your custom instructions here -->\n${PRESERVE_END}`
+}
+
+/**
+ * Wrap content in preserve markers
+ */
+export function wrapInPreserveMarkers(content: string, id?: string): string {
+  const startTag = id ? `<!-- prjct:preserve:${id} -->` : PRESERVE_START
+  return `${startTag}\n${content}\n${PRESERVE_END}`
+}
+
+/**
+ * Remove all preserved sections from content
+ * (Useful for getting the auto-generated portion only)
+ */
+export function stripPreservedSections(content: string): string {
+  const sections = extractPreservedSections(content)
+
+  if (sections.length === 0) {
+    return content
+  }
+
+  // Remove sections in reverse order to preserve indices
+  let result = content
+  for (let i = sections.length - 1; i >= 0; i--) {
+    const section = sections[i]
+    result = result.substring(0, section.startIndex) + result.substring(section.endIndex)
+  }
+
+  // Clean up any resulting double newlines
+  result = result.replace(/\n{3,}/g, '\n\n')
+
+  return result.trim()
+}
+
+/**
+ * Validate that all preserve blocks are properly closed
+ */
+export function validatePreserveBlocks(content: string): {
+  valid: boolean
+  errors: string[]
+} {
+  const errors: string[] = []
+
+  const startMatches = content.match(/<!-- prjct:preserve(?::\w+)? -->/g) || []
+  const endMatches = content.match(/<!-- \/prjct:preserve -->/g) || []
+
+  if (startMatches.length !== endMatches.length) {
+    errors.push(
+      `Mismatched preserve markers: ${startMatches.length} opening, ${endMatches.length} closing`
+    )
+  }
+
+  // Check for nested blocks (not supported)
+  let depth = 0
+  let maxDepth = 0
+  const lines = content.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/<!-- prjct:preserve(?::\w+)? -->/.test(line)) {
+      depth++
+      maxDepth = Math.max(maxDepth, depth)
+    }
+    if (line.includes(PRESERVE_END_PATTERN)) {
+      depth--
+    }
+    if (depth > 1) {
+      errors.push(`Nested preserve blocks detected at line ${i + 1} (not supported)`)
+    }
+    if (depth < 0) {
+      errors.push(`Unexpected closing marker at line ${i + 1}`)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}

package/dist/bin/prjct.mjs

@@ -17217,6 +17217,60 @@ var init_formatters = __esm({
   }
 });
 
+// core/utils/preserve-sections.ts
+function createPreserveStartRegex() {
+  return /<!-- prjct:preserve(?::([\w-]+))? -->/g;
+}
+function extractPreservedSections(content) {
+  const sections = [];
+  const regex = createPreserveStartRegex();
+  let match;
+  let sectionIndex = 0;
+  while ((match = regex.exec(content)) !== null) {
+    const startIndex = match.index;
+    const startTag = match[0];
+    const sectionId = match[1] || `section-${sectionIndex++}`;
+    const endTagStart = content.indexOf(PRESERVE_END_PATTERN, startIndex + startTag.length);
+    if (endTagStart === -1) {
+      continue;
+    }
+    const endIndex = endTagStart + PRESERVE_END_PATTERN.length;
+    const fullContent = content.substring(startIndex, endIndex);
+    sections.push({
+      id: sectionId,
+      content: fullContent,
+      startIndex,
+      endIndex
+    });
+  }
+  return sections;
+}
+function mergePreservedSections(newContent, oldContent) {
+  const preservedSections = extractPreservedSections(oldContent);
+  if (preservedSections.length === 0) {
+    return newContent;
+  }
+  let merged = newContent.trimEnd();
+  merged += "\n\n---\n\n";
+  merged += "## Your Customizations\n\n";
+  merged += "_The sections below are preserved during sync. Edit freely._\n\n";
+  for (const section of preservedSections) {
+    merged += section.content;
+    merged += "\n\n";
+  }
+  return merged.trimEnd() + "\n";
+}
+var PRESERVE_END_PATTERN;
+var init_preserve_sections = __esm({
+  "core/utils/preserve-sections.ts"() {
+    "use strict";
+    PRESERVE_END_PATTERN = "<!-- /prjct:preserve -->";
+    __name(createPreserveStartRegex, "createPreserveStartRegex");
+    __name(extractPreservedSections, "extractPreservedSections");
+    __name(mergePreservedSections, "mergePreservedSections");
+  }
+});
+
 // core/ai-tools/registry.ts
 import { execSync as execSync4 } from "node:child_process";
 import fs34 from "node:fs";
@@ -17356,7 +17410,7 @@ async function generateForTool(context2, config, globalPath, repoPath) {
     };
   }
   try {
-    const content = formatter(context2, config);
+    let content = formatter(context2, config);
     let outputPath;
     if (config.outputPath === "repo") {
       outputPath = path38.join(repoPath, config.outputFile);
@@ -17364,6 +17418,11 @@ async function generateForTool(context2, config, globalPath, repoPath) {
       outputPath = path38.join(globalPath, "context", config.outputFile);
     }
     await fs35.mkdir(path38.dirname(outputPath), { recursive: true });
+    try {
+      const existingContent = await fs35.readFile(outputPath, "utf-8");
+      content = mergePreservedSections(content, existingContent);
+    } catch {
+    }
     await fs35.writeFile(outputPath, content, "utf-8");
     return {
       toolId: config.id,
@@ -17384,6 +17443,7 @@ async function generateForTool(context2, config, globalPath, repoPath) {
 var init_generator2 = __esm({
   "core/ai-tools/generator.ts"() {
     "use strict";
+    init_preserve_sections();
     init_formatters();
     init_registry();
     __name(generateAIToolContexts, "generateAIToolContexts");
@@ -17409,6 +17469,7 @@ var init_context_generator = __esm({
   "core/services/context-generator.ts"() {
     "use strict";
     init_date_helper();
+    init_preserve_sections();
     ContextFileGenerator = class {
       static {
         __name(this, "ContextFileGenerator");
@@ -17515,7 +17576,14 @@ Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
 **Workflow**: ${workflowAgents.join(", ")}
 **Domain**: ${domainAgents.join(", ") || "none"}
 `;
-        await fs36.writeFile(path39.join(contextPath, "CLAUDE.md"), content, "utf-8");
+        const claudePath = path39.join(contextPath, "CLAUDE.md");
+        let finalContent = content;
+        try {
+          const existingContent = await fs36.readFile(claudePath, "utf-8");
+          finalContent = mergePreservedSections(content, existingContent);
+        } catch {
+        }
+        await fs36.writeFile(claudePath, finalContent, "utf-8");
       }
       /**
        * Generate now.md - current task status
@@ -23330,7 +23398,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.45.5",
+      version: "0.46.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.45.5",
+  "version": "0.46.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {