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

package/dist/utils/normalize.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Unit Tests for normalizeMarkdown utility
+ *
+ * Context: MCP clients (GitHub Copilot ≥ v1.0.0, Claude Code, etc.) transmit
+ * multiline strings as literal escape sequences rather than real Unicode control
+ * characters. normalizeMarkdown converts these safely at the ingestion boundary.
+ *
+ * @see BUG-056
+ * @see TASK-270
+ */
+export {};
+//# sourceMappingURL=normalize.test.d.ts.map

package/dist/utils/normalize.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.test.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/utils/normalize.test.js

@@ -0,0 +1,101 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Unit Tests for normalizeMarkdown utility
+ *
+ * Context: MCP clients (GitHub Copilot ≥ v1.0.0, Claude Code, etc.) transmit
+ * multiline strings as literal escape sequences rather than real Unicode control
+ * characters. normalizeMarkdown converts these safely at the ingestion boundary.
+ *
+ * @see BUG-056
+ * @see TASK-270
+ */
+import { describe, expect, it } from 'vitest';
+import { normalizeMarkdown } from './index.js';
+describe('normalizeMarkdown', () => {
+    // ── Core conversion ─────────────────────────────────────────────────────────
+    it('converts literal \\n sequences to real newlines', () => {
+        const input = 'line one\\nline two\\nline three';
+        const result = normalizeMarkdown(input);
+        expect(result).toBe('line one\nline two\nline three');
+        expect(result).toContain('\n');
+        expect(result).not.toContain('\\n');
+    });
+    it('converts literal \\t sequences to real tabs', () => {
+        const input = 'column1\\tcolumn2\\tcolumn3';
+        const result = normalizeMarkdown(input);
+        expect(result).toBe('column1\tcolumn2\tcolumn3');
+        expect(result).toContain('\t');
+        expect(result).not.toContain('\\t');
+    });
+    it('removes literal \\r sequences (stray CR from Windows \\r\\n literals)', () => {
+        const input = 'line one\\r\\nline two';
+        const result = normalizeMarkdown(input);
+        expect(result).toBe('line one\nline two');
+        expect(result).not.toContain('\\r');
+        expect(result).not.toContain('\r');
+    });
+    it('handles all escape sequences together', () => {
+        const input = 'Title\\n\\nParagraph one.\\n\\n- Item 1\\n- Item 2\\n\\n\\tIndented';
+        const result = normalizeMarkdown(input);
+        expect(result).toBe('Title\n\nParagraph one.\n\n- Item 1\n- Item 2\n\n\tIndented');
+    });
+    // ── Idempotency (fast path) ──────────────────────────────────────────────────
+    it('leaves strings with real newlines unchanged (fast path)', () => {
+        const input = 'line one\nline two\nline three';
+        const result = normalizeMarkdown(input);
+        expect(result).toBe(input);
+    });
+    it('is idempotent: calling twice on already-converted string returns same result', () => {
+        const original = 'line one\\nline two';
+        const once = normalizeMarkdown(original);
+        const twice = normalizeMarkdown(once);
+        expect(twice).toBe(once);
+    });
+    it('leaves strings with mixed real newlines and literal \\t unchanged (fast path)', () => {
+        const input = 'line one\nline two\\t still here';
+        const result = normalizeMarkdown(input);
+        // Real newline present → fast path, backslash-t preserved
+        expect(result).toBe(input);
+    });
+    // ── Edge cases ───────────────────────────────────────────────────────────────
+    it('returns empty string unchanged', () => {
+        expect(normalizeMarkdown('')).toBe('');
+    });
+    it('returns plain single-line string unchanged', () => {
+        const input = 'No escape sequences here.';
+        expect(normalizeMarkdown(input)).toBe(input);
+    });
+    it('handles markdown description with heading and list (typical MCP input)', () => {
+        // This is the real-world input that triggered BUG-056
+        const mcpInput = '## Implemented\\n\\n### Show-ServerLayoutEditor\\n- Build `nameToRoles` map before rendering table\\n- Rows with shared hostname → ForegroundColor Yellow + ⚠️ indicator\\n\\n### environment.ps1\\n- After saving: rebuild `$env.Nodes` PSCustomObject';
+        const result = normalizeMarkdown(mcpInput);
+        expect(result).toContain('## Implemented\n');
+        expect(result).toContain('### Show-ServerLayoutEditor\n');
+        expect(result).toContain('- Build `nameToRoles`');
+        expect(result).not.toContain('\\n');
+    });
+    it('handles default description template with real newlines (CLI usage)', () => {
+        // CLI users provide real newlines — must NOT be double-converted
+        const cliInput = '# My Story\n\n<!-- Add detailed description here -->\n';
+        const result = normalizeMarkdown(cliInput);
+        expect(result).toBe(cliInput);
+    });
+    it('handles string with only whitespace', () => {
+        expect(normalizeMarkdown('   ')).toBe('   ');
+        expect(normalizeMarkdown('\n')).toBe('\n'); // real newline → fast path
+    });
+    it('preserves Unicode characters correctly', () => {
+        const input = 'Emoji: ⚠️\\nArrow: →\\nUmlaut: äöü';
+        const result = normalizeMarkdown(input);
+        expect(result).toBe('Emoji: ⚠️\nArrow: →\nUmlaut: äöü');
+    });
+    // ── append_description use case ──────────────────────────────────────────────
+    it('normalizes text intended for append_description correctly', () => {
+        const appendContent = '\\n\\n## Added in v2\\n- New feature X\\n- Fixed issue Y';
+        const result = normalizeMarkdown(appendContent);
+        expect(result).toBe('\n\n## Added in v2\n- New feature X\n- Fixed issue Y');
+    });
+});
+//# sourceMappingURL=normalize.test.js.map

package/dist/utils/normalize.test.js.map

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

package/dist/utils/update-copilot-files.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * GitHub Copilot files update utilities
+ * Compares installed devsteps-managed .github files against the package source
+ * using SHA-256 hashes stored in HTML comments, then selectively updates changed
+ * files after creating a timestamped backup.
+ */
+export interface FileUpdateStatus {
+    file: string;
+    status: 'updated' | 'skipped' | 'added';
+    reason?: string;
+}
+export interface UpdateCopilotFilesResult {
+    success: boolean;
+    updatedCount: number;
+    skippedCount: number;
+    addedCount: number;
+    backupDir: string;
+    files: FileUpdateStatus[];
+    message: string;
+    error?: string;
+}
+export interface UpdateCopilotFilesOptions {
+    /** DevSteps package version (for comment annotation) */
+    packageVersion?: string;
+    /** Maximum backup rotations to keep (default: 5) */
+    maxBackups?: number;
+    /**
+     * If true, report what would change but do not write anything.
+     * No backup is created in dry-run mode.
+     */
+    dryRun?: boolean;
+    /** If true, overwrite even when hashes match (force reinstall) */
+    force?: boolean;
+}
+/**
+ * Update all devsteps-managed .github Copilot files in a target project.
+ *
+ * Algorithm per source file:
+ *   1. Compute sha256 of raw source content (before annotation).
+ *   2. If a corresponding file exists in the target:
+ *      a. Extract the stored hash from its devsteps HTML comment.
+ *      b. If hashes match (and `force` is not set): skip — no change needed.
+ *      c. If hashes differ: mark as "update" candidate.
+ *   3. If no corresponding file exists: mark as "add" candidate.
+ * After collecting candidates:
+ *   4. If there are changes and not dryRun: create a backup first.
+ *      Abort on backup failure (prevents partial states).
+ *   5. Write each candidate with a fresh `injectDevstepsComment`.
+ *
+ * @param sourceGithubDir  Path to the package's bundled `.github` directory.
+ * @param targetGithubDir  Path to the target project's `.github` directory.
+ * @param devstepsDir      Path to the target project's `.devsteps` directory (for backups).
+ * @param options          Optional settings.
+ */
+export declare function updateCopilotFiles(sourceGithubDir: string, targetGithubDir: string, devstepsDir: string, options?: UpdateCopilotFilesOptions): UpdateCopilotFilesResult;
+//# sourceMappingURL=update-copilot-files.d.ts.map

package/dist/utils/update-copilot-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-copilot-files.d.ts","sourceRoot":"","sources":["../../src/utils/update-copilot-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2BH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,yBAAyB,GAClC,wBAAwB,CAqJ1B"}

package/dist/utils/update-copilot-files.js

@@ -0,0 +1,183 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * GitHub Copilot files update utilities
+ * Compares installed devsteps-managed .github files against the package source
+ * using SHA-256 hashes stored in HTML comments, then selectively updates changed
+ * files after creating a timestamped backup.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { backupGithubFiles } from './backup-github-files.js';
+import { injectDevstepsComment } from './init-helpers.js';
+/** Regex that matches `<!-- devsteps-managed: ... | hash: sha256:<hex> ... -->` */
+const MANAGED_COMMENT_RE = /<!--\s*devsteps-managed:.*?hash:\s*sha256:([0-9a-f]{64}).*?-->/;
+/**
+ * Extract the sha256 hash embedded in a devsteps-managed HTML comment.
+ * Returns null if the file is not managed or has no hash.
+ */
+function extractManagedHash(content) {
+    const match = content.match(MANAGED_COMMENT_RE);
+    return match ? match[1] : null;
+}
+/**
+ * Compute sha256 of content (UTF-8) — same function used by injectDevstepsComment.
+ */
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+const SUBDIRS = [
+    { sub: 'agents', suffix: '.agent.md' },
+    { sub: 'instructions', suffix: '.instructions.md' },
+    { sub: 'prompts', suffix: '.prompt.md' },
+];
+/**
+ * Update all devsteps-managed .github Copilot files in a target project.
+ *
+ * Algorithm per source file:
+ *   1. Compute sha256 of raw source content (before annotation).
+ *   2. If a corresponding file exists in the target:
+ *      a. Extract the stored hash from its devsteps HTML comment.
+ *      b. If hashes match (and `force` is not set): skip — no change needed.
+ *      c. If hashes differ: mark as "update" candidate.
+ *   3. If no corresponding file exists: mark as "add" candidate.
+ * After collecting candidates:
+ *   4. If there are changes and not dryRun: create a backup first.
+ *      Abort on backup failure (prevents partial states).
+ *   5. Write each candidate with a fresh `injectDevstepsComment`.
+ *
+ * @param sourceGithubDir  Path to the package's bundled `.github` directory.
+ * @param targetGithubDir  Path to the target project's `.github` directory.
+ * @param devstepsDir      Path to the target project's `.devsteps` directory (for backups).
+ * @param options          Optional settings.
+ */
+export function updateCopilotFiles(sourceGithubDir, targetGithubDir, devstepsDir, options) {
+    const packageVersion = options?.packageVersion ?? 'unknown';
+    const dryRun = options?.dryRun ?? false;
+    const force = options?.force ?? false;
+    const maxBackups = options?.maxBackups ?? 5;
+    const fileStatuses = [];
+    const updateCandidates = [];
+    // ── Phase 1: Diff source vs. target ─────────────────────────────────────────
+    for (const { sub, suffix } of SUBDIRS) {
+        const sourceSubDir = join(sourceGithubDir, sub);
+        const targetSubDir = join(targetGithubDir, sub);
+        if (!existsSync(sourceSubDir))
+            continue;
+        const sourceFiles = readdirSync(sourceSubDir).filter((f) => f.startsWith('devsteps') && f.endsWith(suffix));
+        for (const file of sourceFiles) {
+            const sourceFile = join(sourceSubDir, file);
+            const targetFile = join(targetSubDir, file);
+            const rawContent = readFileSync(sourceFile, 'utf8');
+            const sourceHash = sha256(rawContent);
+            const rel = `${sub}/${file}`;
+            if (existsSync(targetFile)) {
+                const installed = readFileSync(targetFile, 'utf8');
+                const installedHash = extractManagedHash(installed);
+                if (!force && installedHash === sourceHash) {
+                    fileStatuses.push({ file: rel, status: 'skipped', reason: 'hash-match' });
+                    continue;
+                }
+                const reasonSuffix = installedHash === null
+                    ? 'no-marker'
+                    : force
+                        ? 'force'
+                        : 'hash-mismatch';
+                updateCandidates.push({ sourceFile, targetFile, rawContent, hash: sourceHash, rel, status: 'updated' });
+                fileStatuses.push({ file: rel, status: 'updated', reason: reasonSuffix });
+            }
+            else {
+                updateCandidates.push({ sourceFile, targetFile, rawContent, hash: sourceHash, rel, status: 'added' });
+                fileStatuses.push({ file: rel, status: 'added' });
+            }
+        }
+    }
+    const updatedCount = fileStatuses.filter((f) => f.status === 'updated').length;
+    const skippedCount = fileStatuses.filter((f) => f.status === 'skipped').length;
+    const addedCount = fileStatuses.filter((f) => f.status === 'added').length;
+    // ── Phase 2: If nothing to do, return early ──────────────────────────────────
+    if (updateCandidates.length === 0) {
+        return {
+            success: true,
+            updatedCount: 0,
+            skippedCount,
+            addedCount: 0,
+            backupDir: '',
+            files: fileStatuses,
+            message: `All ${skippedCount} files are up-to-date. No changes needed.`,
+        };
+    }
+    if (dryRun) {
+        const summary = [
+            updatedCount > 0 ? `${updatedCount} to update` : '',
+            addedCount > 0 ? `${addedCount} to add` : '',
+            skippedCount > 0 ? `${skippedCount} unchanged` : '',
+        ]
+            .filter(Boolean)
+            .join(', ');
+        return {
+            success: true,
+            updatedCount,
+            skippedCount,
+            addedCount,
+            backupDir: '',
+            files: fileStatuses,
+            message: `[dry-run] Would apply: ${summary}`,
+        };
+    }
+    // ── Phase 3: Backup before writing ───────────────────────────────────────────
+    const backupResult = backupGithubFiles(targetGithubDir, devstepsDir, {
+        maxBackups,
+        packageVersion,
+    });
+    if (!backupResult.success) {
+        return {
+            success: false,
+            updatedCount: 0,
+            skippedCount,
+            addedCount: 0,
+            backupDir: backupResult.backupDir,
+            files: fileStatuses,
+            message: 'Backup failed — update aborted to prevent partial state.',
+            error: backupResult.error?.message ?? 'Unknown backup error',
+        };
+    }
+    // ── Phase 4: Write updated files ─────────────────────────────────────────────
+    try {
+        for (const candidate of updateCandidates) {
+            const annotated = injectDevstepsComment(candidate.rawContent, candidate.hash, packageVersion);
+            writeFileSync(candidate.targetFile, annotated, 'utf8');
+        }
+    }
+    catch (writeError) {
+        return {
+            success: false,
+            updatedCount,
+            skippedCount,
+            addedCount,
+            backupDir: backupResult.backupDir,
+            files: fileStatuses,
+            message: `Write error after backup. Backup preserved at: ${backupResult.backupDir}`,
+            error: writeError instanceof Error ? writeError.message : String(writeError),
+        };
+    }
+    const summary = [
+        updatedCount > 0 ? `${updatedCount} updated` : '',
+        addedCount > 0 ? `${addedCount} added` : '',
+        skippedCount > 0 ? `${skippedCount} unchanged` : '',
+    ]
+        .filter(Boolean)
+        .join(', ');
+    return {
+        success: true,
+        updatedCount,
+        skippedCount,
+        addedCount,
+        backupDir: backupResult.backupDir,
+        files: fileStatuses,
+        message: `Copilot files updated (${summary}).${backupResult.fileCount > 0 ? ` Backup: ${backupResult.backupDir}` : ''}`,
+    };
+}
+//# sourceMappingURL=update-copilot-files.js.map

package/dist/utils/update-copilot-files.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schnick371/devsteps-shared",
-  "version": "1.1.0-next.2",
+  "version": "1.1.0-next.4",
   "license": "Apache-2.0",
   "description": "Never Code Alone. Shared types, schemas, and utilities for DevSteps task tracking.",
   "author": "Thomas Hertel <thomas.hertel@devsteps.dev>",