@schnick371/devsteps-shared 1.1.0-next.2 → 1.1.0-next.3

package/dist/core/context.test.js

@@ -0,0 +1,239 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Tests for context generation — quick/standard levels, context_meta, generateProjectMd
+ *
+ * @see STORY-121 TASK-273, TASK-276
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildContextMeta, formatContextAsText, generateProjectMd, getQuickContext, getStandardContext, } from './context.js';
+// ─── Test fixtures ────────────────────────────────────────────────────────────
+function makeIndex(items) {
+    return JSON.stringify({
+        version: '2.0.0',
+        items,
+    });
+}
+function makeItem(id, type, status) {
+    return { id, type, title: `${type} ${id}`, status, updated: new Date().toISOString() };
+}
+let tmpDir;
+let projectDir;
+let devstepsDir;
+beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(tmpdir(), 'devsteps-ctx-test-'));
+    projectDir = tmpDir;
+    devstepsDir = path.join(tmpDir, '.devsteps');
+    mkdirSync(devstepsDir, { recursive: true });
+    // Minimal index
+    writeFileSync(path.join(devstepsDir, 'index.json'), makeIndex([
+        makeItem('STORY-001', 'story', 'in-progress'),
+        makeItem('TASK-001', 'task', 'planned'),
+        makeItem('TASK-002', 'task', 'done'),
+        makeItem('BUG-001', 'bug', 'blocked'),
+    ]));
+});
+afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+// ─── getQuickContext ──────────────────────────────────────────────────────────
+describe('getQuickContext', () => {
+    it('returns success with correct context_level', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.context_level).toBe('quick');
+    });
+    it('includes active_items counts', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.dynamic_context.active_items.total).toBe(4);
+        expect(ctx.dynamic_context.active_items.by_type.story).toBe(1);
+        expect(ctx.dynamic_context.active_items.by_status.done).toBe(1);
+    });
+    it('includes context_meta', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.context_meta).toBeDefined();
+        expect(ctx.context_meta.level).toBe('quick');
+        expect(typeof ctx.context_meta.generated_at).toBe('string');
+        expect(typeof ctx.context_meta.project_md_age_hours).toBe('number');
+        expect(typeof ctx.context_meta.is_stale).toBe('boolean');
+        expect(typeof ctx.context_meta.cache_hit).toBe('boolean');
+    });
+    it('context_meta.is_stale true when PROJECT.md missing', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        // PROJECT.md not written in beforeEach — should be stale (Infinity age)
+        expect(ctx.context_meta.is_stale).toBe(true);
+        expect(ctx.context_meta.project_md_age_hours).toBe(Number.POSITIVE_INFINITY);
+    });
+    it('context_meta.is_stale false when PROJECT.md is fresh', async () => {
+        writeFileSync(path.join(devstepsDir, 'PROJECT.md'), '# Test', 'utf-8');
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.context_meta.is_stale).toBe(false);
+        expect(ctx.context_meta.project_md_age_hours).toBeLessThan(1);
+    });
+    it('includes suggestions when PROJECT.md missing', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.suggestions).toBeDefined();
+        expect(ctx.suggestions.some((s) => s.includes('devsteps context generate'))).toBe(true);
+    });
+    it('includes suggestions for blocked items', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.suggestions.some((s) => s.includes('blocked'))).toBe(true);
+    });
+    it('tokens_used is positive', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        expect(ctx.tokens_used).toBeGreaterThan(0);
+    });
+});
+// ─── getStandardContext ───────────────────────────────────────────────────────
+describe('getStandardContext', () => {
+    it('returns context_level standard', async () => {
+        const ctx = await getStandardContext(projectDir, devstepsDir);
+        expect(ctx.context_level).toBe('standard');
+    });
+    it('includes context_meta with level standard', async () => {
+        const ctx = await getStandardContext(projectDir, devstepsDir);
+        expect(ctx.context_meta).toBeDefined();
+        expect(ctx.context_meta.level).toBe('standard');
+    });
+    it('standard context includes open_items_count in dynamic_context', async () => {
+        const ctx = await getStandardContext(projectDir, devstepsDir);
+        // 4 items total, 3 non-done (in-progress, planned, blocked)
+        const dc = ctx.dynamic_context;
+        expect(dc.open_items_count).toBeDefined();
+        expect(dc.open_items_count).toBeGreaterThanOrEqual(3);
+    });
+    it('standard context includes in_progress array', async () => {
+        const ctx = await getStandardContext(projectDir, devstepsDir);
+        const dc = ctx.dynamic_context;
+        expect(dc.in_progress).toBeDefined();
+        expect(dc.in_progress.some((i) => i.id === 'STORY-001')).toBe(true);
+    });
+    it('standard context includes blocking_items array', async () => {
+        const ctx = await getStandardContext(projectDir, devstepsDir);
+        const dc = ctx.dynamic_context;
+        expect(dc.blocking_items).toBeDefined();
+        expect(dc.blocking_items.some((i) => i.id === 'BUG-001')).toBe(true);
+    });
+    it('tokens_used is positive and larger than quick', async () => {
+        const quick = await getQuickContext(projectDir, devstepsDir);
+        const standard = await getStandardContext(projectDir, devstepsDir);
+        expect(standard.tokens_used).toBeGreaterThan(0);
+        // Standard should be at least as many tokens as quick
+        expect(standard.tokens_used).toBeGreaterThanOrEqual(quick.tokens_used);
+    });
+});
+// ─── buildContextMeta ────────────────────────────────────────────────────────
+describe('buildContextMeta', () => {
+    it('returns is_stale true when PROJECT.md missing', async () => {
+        const meta = await buildContextMeta(devstepsDir, 'quick', false);
+        expect(meta.is_stale).toBe(true);
+    });
+    it('returns is_stale false when PROJECT.md fresh', async () => {
+        writeFileSync(path.join(devstepsDir, 'PROJECT.md'), '# test', 'utf-8');
+        const meta = await buildContextMeta(devstepsDir, 'quick', false);
+        expect(meta.is_stale).toBe(false);
+    });
+    it('returns correct level', async () => {
+        const meta = await buildContextMeta(devstepsDir, 'standard', true);
+        expect(meta.level).toBe('standard');
+        expect(meta.cache_hit).toBe(true);
+    });
+    it('generated_at is valid ISO date', async () => {
+        const meta = await buildContextMeta(devstepsDir, 'quick', false);
+        expect(new Date(meta.generated_at).getTime()).not.toBeNaN();
+    });
+});
+// ─── formatContextAsText ─────────────────────────────────────────────────────
+describe('formatContextAsText', () => {
+    it('produces non-empty markdown string', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        const text = formatContextAsText(ctx);
+        expect(typeof text).toBe('string');
+        expect(text.length).toBeGreaterThan(50);
+    });
+    it('contains project status section', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        const text = formatContextAsText(ctx);
+        expect(text).toContain('## Project Status');
+        expect(text).toContain('Total items: 4');
+    });
+    it('contains DevSteps Conventions section', async () => {
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        const text = formatContextAsText(ctx);
+        expect(text).toContain('## DevSteps Conventions');
+        expect(text).toContain('.devsteps/');
+    });
+    it('includes stale warning when is_stale', async () => {
+        // PROJECT.md missing => is_stale
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        const text = formatContextAsText(ctx);
+        expect(text).toContain('stale');
+        expect(text).toContain('devsteps context generate');
+    });
+    it('no stale warning when PROJECT.md fresh', async () => {
+        writeFileSync(path.join(devstepsDir, 'PROJECT.md'), '# test', 'utf-8');
+        const ctx = await getQuickContext(projectDir, devstepsDir);
+        const text = formatContextAsText(ctx);
+        expect(text).not.toContain('stale');
+    });
+});
+// ─── generateProjectMd ───────────────────────────────────────────────────────
+describe('generateProjectMd', () => {
+    beforeEach(() => {
+        // Write a minimal config.json
+        writeFileSync(path.join(devstepsDir, 'config.json'), JSON.stringify({
+            project_name: 'test-project',
+            settings: { methodology: 'scrum' },
+            created: new Date().toISOString(),
+        }), 'utf-8');
+    });
+    it('produces markdown starting with project name', async () => {
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toMatch(/^# test-project/);
+    });
+    it('contains Project Type section', async () => {
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toContain('## Project Type');
+        expect(md).toContain('Scrum');
+    });
+    it('contains Status section with item counts', async () => {
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toContain('## Status');
+        expect(md).toContain('Total items: 4');
+    });
+    it('contains Conventions section', async () => {
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toContain('## Conventions');
+        expect(md).toContain('.devsteps/');
+    });
+    it('ends with generation timestamp', async () => {
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toContain('_Generated by');
+        expect(md).toContain('devsteps context generate');
+    });
+    it('reads description from README.md when no config description', async () => {
+        writeFileSync(path.join(projectDir, 'README.md'), '# Test\n\nThis is the first paragraph.', 'utf-8');
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toContain('This is the first paragraph.');
+    });
+    it('includes package structure when packages/ dir exists', async () => {
+        const pkgDir = path.join(projectDir, 'packages', 'mypkg');
+        mkdirSync(pkgDir, { recursive: true });
+        writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name: '@test/mypkg', description: 'My test package' }), 'utf-8');
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        expect(md).toContain('## Package Structure');
+        expect(md).toContain('@test/mypkg');
+        expect(md).toContain('My test package');
+    });
+    it('works when config.json is missing (graceful fallback)', async () => {
+        rmSync(path.join(devstepsDir, 'config.json'));
+        const md = await generateProjectMd(projectDir, devstepsDir);
+        // Should not throw — uses directory name as project name
+        expect(md).toBeDefined();
+        expect(md.startsWith('#')).toBe(true);
+    });
+});
+//# sourceMappingURL=context.test.js.map

package/dist/core/context.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.js","sourceRoot":"","sources":["../../src/core/context.test.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -10,7 +10,7 @@ export { type ArchiveItemResult, archiveItem, type PurgeItemsArgs, type PurgeIte
 export { type AutoMigrationOptions, checkMigrationNeeded, ensureFullMigration, ensureIndexMigrated, getMigrationStatusMessage, type MigrationCheckResult, type MigrationStats, migrateItemsDirectory, needsItemsDirectoryMigration, performMigration, } from './auto-migrate.js';
 export { type BulkUpdateResult, bulkAddTags, bulkRemoveTags, bulkUpdateItems, } from './bulk-update.js';
 export { getConfig } from './config.js';
-export { analyzePackages, estimateTokens, getItemCounts, getQuickContext, getRecentUpdates, readProjectMd, } from './context.js';
+export { analyzePackages, buildContextMeta, type ContextMeta, estimateTokens, formatContextAsText, generateProjectMd, getItemCounts, getQuickContext, getRecentUpdates, getStandardContext, readProjectMd, } from './context.js';
 export { type GetItemResult, getItem } from './get.js';
 export { type RebuildOptions, type RebuildResult, rebuildIndex, } from './index-rebuild.js';
 export * from './index-refs.js';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EACL,KAAK,iBAAiB,EACtB,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,gBAAgB,EACrB,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEvD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EACL,KAAK,gBAAgB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EACL,KAAK,iBAAiB,EACtB,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,gBAAgB,EACrB,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,KAAK,WAAW,EAChB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEvD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EACL,KAAK,gBAAgB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAC"}

package/dist/core/index.js

@@ -11,7 +11,7 @@ export { archiveItem, purgeItems, } from './archive.js';
 export { checkMigrationNeeded, ensureFullMigration, ensureIndexMigrated, getMigrationStatusMessage, migrateItemsDirectory, needsItemsDirectoryMigration, performMigration, } from './auto-migrate.js';
 export { bulkAddTags, bulkRemoveTags, bulkUpdateItems, } from './bulk-update.js';
 export { getConfig } from './config.js';
-export { analyzePackages, estimateTokens, getItemCounts, getQuickContext, getRecentUpdates, readProjectMd, } from './context.js';
+export { analyzePackages, buildContextMeta, estimateTokens, formatContextAsText, generateProjectMd, getItemCounts, getQuickContext, getRecentUpdates, getStandardContext, readProjectMd, } from './context.js';
 export { getItem } from './get.js';
 // Index rebuild operations
 export { rebuildIndex, } from './index-rebuild.js';

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAwC,OAAO,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAEL,WAAW,EAGX,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,uCAAuC;AACvC,OAAO,EAEL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EAGzB,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAsB,OAAO,EAAE,MAAM,UAAU,CAAC;AACvD,2BAA2B;AAC3B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,8BAA8B;AAC9B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAA4C,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAA0C,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAGL,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAA8C,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAEL,wBAAwB,EACxB,oBAAoB,GAErB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAwC,OAAO,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAEL,WAAW,EAGX,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,uCAAuC;AACvC,OAAO,EAEL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EAGzB,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,eAAe,EACf,gBAAgB,EAEhB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAsB,OAAO,EAAE,MAAM,UAAU,CAAC;AACvD,2BAA2B;AAC3B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,8BAA8B;AAC9B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAA4C,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAA0C,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAGL,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAA8C,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAEL,wBAAwB,EACxB,oBAAoB,GAErB,MAAM,iBAAiB,CAAC"}

package/dist/core/update.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { RELATIONSHIP_TYPE, STATUS } from '../constants/index.js';
-import { getCurrentTimestamp, parseItemId, TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { getCurrentTimestamp, normalizeMarkdown, parseItemId, TYPE_TO_DIRECTORY } from '../utils/index.js';
 import { getItem } from './get.js';
 import { updateItemInIndex } from './index-refs.js';
 /**
@@ -91,13 +91,13 @@ export async function updateItem(devstepsDir, args) {
         throw new Error('Cannot use both description and append_description simultaneously');
     }
     if (args.description) {
-        // Replace entire description
-        writeFileSync(descriptionPath, args.description);
+        // Replace entire description — normalize escape sequences from MCP clients (BUG-056)
+        writeFileSync(descriptionPath, normalizeMarkdown(args.description));
     }
     else if (args.append_description) {
         // Append to existing (or create new if doesn't exist)
         const existing = existsSync(descriptionPath) ? readFileSync(descriptionPath, 'utf-8') : '';
-        writeFileSync(descriptionPath, existing + args.append_description);
+        writeFileSync(descriptionPath, existing + normalizeMarkdown(args.append_description));
     }
     // Update index (auto-migration ensures refs-style always available)
     // Only update if status or eisenhower changed (triggers re-indexing)

package/dist/core/update.js.map

@@ -1 +1 @@
-{"version":3,"file":"update.js","sourceRoot":"","sources":["../../src/core/update.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../src/core/update.ts"],"names":[],"mappings":"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"}

package/dist/utils/backup-github-files.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * GitHub Copilot file backup utilities
+ * Creates timestamped backups of devsteps-managed .github files before updates.
+ */
+export interface BackupResult {
+    success: boolean;
+    backupDir: string;
+    timestamp: string;
+    fileCount: number;
+    files: string[];
+    error?: Error;
+}
+export interface BackupOptions {
+    /** Maximum number of backups to retain (default: 5) */
+    maxBackups?: number;
+    /** DevSteps package version for manifest */
+    packageVersion?: string;
+    /** Skip backup entirely (dry-run / test mode) */
+    skip?: boolean;
+}
+/**
+ * Create a timestamped backup of all devsteps-managed .github files.
+ *
+ * Backup location: `<devstepsDir>/backups/github-<timestamp>/`
+ * A `manifest.json` is written alongside the backed-up files.
+ *
+ * On any error the partially-created backup directory is cleaned up
+ * and `success: false` is returned — callers must abort the update.
+ */
+export declare function backupGithubFiles(githubDir: string, devstepsDir: string, options?: BackupOptions): BackupResult;
+//# sourceMappingURL=backup-github-files.d.ts.map

package/dist/utils/backup-github-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-github-files.d.ts","sourceRoot":"","sources":["../../src/utils/backup-github-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA8DD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CA6Ed"}

package/dist/utils/backup-github-files.js

@@ -0,0 +1,137 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * GitHub Copilot file backup utilities
+ * Creates timestamped backups of devsteps-managed .github files before updates.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+const DEFAULT_MAX_BACKUPS = 5;
+const BACKUP_DIR_PREFIX = 'github-';
+/**
+ * Compute sha256 hex digest of a string.
+ */
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/**
+ * Format a Date as a filesystem-safe ISO timestamp: YYYY-MM-DDTHH-MM-SS
+ */
+function formatTimestamp(date) {
+    return date
+        .toISOString()
+        .replace(/\.\d{3}Z$/, '')
+        .replace(/:/g, '-');
+}
+/**
+ * Collect all devsteps-managed .github files from the three subdirectories.
+ * Returns an array of { rel, abs } objects where rel is the subdirectory-relative path.
+ */
+function collectManagedFiles(githubDir) {
+    const subdirs = ['agents', 'instructions', 'prompts'];
+    const collected = [];
+    for (const sub of subdirs) {
+        const dir = join(githubDir, sub);
+        if (!existsSync(dir))
+            continue;
+        const files = readdirSync(dir).filter((f) => f.startsWith('devsteps') && (f.endsWith('.agent.md') || f.endsWith('.instructions.md') || f.endsWith('.prompt.md')));
+        for (const file of files) {
+            collected.push({ rel: join(sub, file), abs: join(dir, file) });
+        }
+    }
+    return collected;
+}
+/**
+ * Remove oldest backup directories, keeping only `maxBackups` most recent.
+ */
+function pruneOldBackups(backupsRoot, maxBackups) {
+    if (!existsSync(backupsRoot))
+        return;
+    const entries = readdirSync(backupsRoot)
+        .filter((d) => d.startsWith(BACKUP_DIR_PREFIX))
+        .sort(); // ISO-ish timestamps sort lexicographically
+    const toRemove = entries.slice(0, Math.max(0, entries.length - maxBackups));
+    for (const dir of toRemove) {
+        rmSync(join(backupsRoot, dir), { recursive: true, force: true });
+    }
+}
+/**
+ * Create a timestamped backup of all devsteps-managed .github files.
+ *
+ * Backup location: `<devstepsDir>/backups/github-<timestamp>/`
+ * A `manifest.json` is written alongside the backed-up files.
+ *
+ * On any error the partially-created backup directory is cleaned up
+ * and `success: false` is returned — callers must abort the update.
+ */
+export function backupGithubFiles(githubDir, devstepsDir, options) {
+    const maxBackups = options?.maxBackups ?? DEFAULT_MAX_BACKUPS;
+    const packageVersion = options?.packageVersion ?? 'unknown';
+    const timestamp = formatTimestamp(new Date());
+    if (options?.skip) {
+        return { success: true, backupDir: '', timestamp, fileCount: 0, files: [] };
+    }
+    const backupsRoot = join(devstepsDir, 'backups');
+    const backupDir = join(backupsRoot, `${BACKUP_DIR_PREFIX}${timestamp}`);
+    let partiallyCreated = false;
+    try {
+        const managedFiles = collectManagedFiles(githubDir);
+        if (managedFiles.length === 0) {
+            // Nothing to back up — not an error
+            return { success: true, backupDir: '', timestamp, fileCount: 0, files: [] };
+        }
+        // Create backup directory structure
+        mkdirSync(join(backupDir, 'agents'), { recursive: true });
+        mkdirSync(join(backupDir, 'instructions'), { recursive: true });
+        mkdirSync(join(backupDir, 'prompts'), { recursive: true });
+        partiallyCreated = true;
+        const manifestEntries = [];
+        const copiedFiles = [];
+        for (const { rel, abs } of managedFiles) {
+            const dest = join(backupDir, rel);
+            copyFileSync(abs, dest);
+            const content = readFileSync(abs, 'utf8');
+            manifestEntries.push({ file: rel, sha256: sha256(content) });
+            copiedFiles.push(rel);
+        }
+        // Write manifest
+        const manifest = {
+            timestamp,
+            packageVersion,
+            githubDir,
+            files: manifestEntries,
+        };
+        writeFileSync(join(backupDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        // Prune old backups AFTER successful write
+        pruneOldBackups(backupsRoot, maxBackups);
+        return {
+            success: true,
+            backupDir,
+            timestamp,
+            fileCount: copiedFiles.length,
+            files: copiedFiles,
+        };
+    }
+    catch (error) {
+        // Clean up partial backup to avoid corrupted state
+        if (partiallyCreated) {
+            try {
+                rmSync(backupDir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort cleanup — ignore secondary errors
+            }
+        }
+        return {
+            success: false,
+            backupDir,
+            timestamp,
+            fileCount: 0,
+            files: [],
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+//# sourceMappingURL=backup-github-files.js.map

package/dist/utils/backup-github-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-github-files.js","sourceRoot":"","sources":["../../src/utils/backup-github-files.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -7,7 +7,9 @@
  */
 import type { ItemType, Methodology } from '../schemas/index.js';
 export { CACHE_CONFIG, type CacheStats, ContextCache, clearGlobalCache, getCache, } from './cache.js';
-export { type CopiedGithubFiles, copyDevstepsDocs, copyGithubFiles, writeSetupMd, } from './init-helpers.js';
+export { type BackupOptions, type BackupResult, backupGithubFiles, } from './backup-github-files.js';
+export { type CopiedGithubFiles, copyDevstepsDocs, copyGithubFiles, injectDevstepsComment, writeSetupMd, } from './init-helpers.js';
+export { type UpdateCopilotFilesOptions, type UpdateCopilotFilesResult, updateCopilotFiles, } from './update-copilot-files.js';
 /**
  * Type to plural directory mapping
  * Uses items/ subdirectory for git-inspired object store (SPIKE-008)
@@ -84,4 +86,26 @@ export declare function isValidEmail(email: string): boolean;
  * Sanitizes a string for use in filenames
  */
 export declare function sanitizeFilename(name: string): string;
+/**
+ * Normalizes escape sequences in description strings received from MCP tool calls.
+ *
+ * **Problem:** MCP clients (GitHub Copilot ≥ v1.0.0, Claude Code, etc.) transmit
+ * multiline strings with literal two-character sequences `\n`, `\t` instead of
+ * actual Unicode control characters. `JSON.parse` delivers these sequences unchanged,
+ * so `writeFileSync` writes them verbatim — producing unreadable `.md` files.
+ *
+ * **Heuristic:** If the incoming string already contains real newlines (U+000A),
+ * it is already properly formatted and returned unchanged. This makes the function
+ * safe to call on both MCP-origin strings and CLI-origin strings, and prevents
+ * double-conversion.
+ *
+ * **Handles:**
+ * - `\n` (backslash + n) → real newline (LF)
+ * - `\t` (backslash + t) → real tab
+ * - `\r` (backslash + r) → removed (stray CR from Windows-style `\r\n` literals)
+ *
+ * @param value - The raw description string from an MCP tool argument
+ * @returns A string with proper newline characters suitable for file I/O
+ */
+export declare function normalizeMarkdown(value: string): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGjE,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,YAAY,EACZ,gBAAgB,EAChB,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,eAAe,EACf,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW;gBAGU,QAAQ,EAAE;;;;;;;;;;;gBAmBD,QAAQ,EAAE;;;;;;;;;;;gBA4B/E,QAAQ,EAAE;;;;;;;;;;;;EAyBpB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAgBR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmBjF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGtD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGjE,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,YAAY,EACZ,gBAAgB,EAChB,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW;gBAGU,QAAQ,EAAE;;;;;;;;;;;gBAmBD,QAAQ,EAAE;;;;;;;;;;;gBA4B/E,QAAQ,EAAE;;;;;;;;;;;;EAyBpB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAgBR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmBjF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGtD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvD"}

package/dist/utils/index.js

@@ -7,8 +7,12 @@
  */
 // Export cache utilities
 export { CACHE_CONFIG, ContextCache, clearGlobalCache, getCache, } from './cache.js';
+// Export backup utilities
+export { backupGithubFiles, } from './backup-github-files.js';
 // Export init helpers
-export { copyDevstepsDocs, copyGithubFiles, writeSetupMd, } from './init-helpers.js';
+export { copyDevstepsDocs, copyGithubFiles, injectDevstepsComment, writeSetupMd, } from './init-helpers.js';
+// Export update helpers
+export { updateCopilotFiles, } from './update-copilot-files.js';
 /**
  * Type to plural directory mapping
  * Uses items/ subdirectory for git-inspired object store (SPIKE-008)
@@ -187,4 +191,35 @@ export function sanitizeFilename(name) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
 }
+/**
+ * Normalizes escape sequences in description strings received from MCP tool calls.
+ *
+ * **Problem:** MCP clients (GitHub Copilot ≥ v1.0.0, Claude Code, etc.) transmit
+ * multiline strings with literal two-character sequences `\n`, `\t` instead of
+ * actual Unicode control characters. `JSON.parse` delivers these sequences unchanged,
+ * so `writeFileSync` writes them verbatim — producing unreadable `.md` files.
+ *
+ * **Heuristic:** If the incoming string already contains real newlines (U+000A),
+ * it is already properly formatted and returned unchanged. This makes the function
+ * safe to call on both MCP-origin strings and CLI-origin strings, and prevents
+ * double-conversion.
+ *
+ * **Handles:**
+ * - `\n` (backslash + n) → real newline (LF)
+ * - `\t` (backslash + t) → real tab
+ * - `\r` (backslash + r) → removed (stray CR from Windows-style `\r\n` literals)
+ *
+ * @param value - The raw description string from an MCP tool argument
+ * @returns A string with proper newline characters suitable for file I/O
+ */
+export function normalizeMarkdown(value) {
+    // Fast path: real newlines are present → already properly formatted
+    if (value.includes('\n'))
+        return value;
+    // Slow path: convert MCP-style escape sequences to real control characters
+    return value
+        .replace(/\\n/g, '\n')
+        .replace(/\\t/g, '\t')
+        .replace(/\\r/g, '');
+}
 //# sourceMappingURL=index.js.map