@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/utils/agent-files-snapshot.js

@@ -0,0 +1,128 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Complete exact-byte pre-write snapshots for the existing Copilot/Claude updater.
+ */
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { byteHash, readSnapshotBytes, recognizedSnapshot, SNAPSHOT_FORMAT, } from './snapshot-manifest.js';
+import { assertSafeDirectory, assertSafeFile, assertUniqueKeys, pathEntry, validateBackupsRoot, workspacePath, } from './snapshot-paths.js';
+import { BACKUP_DIR_PREFIX, cleanIncompleteSnapshot, pruneSnapshots, } from './snapshot-retention.js';
+export function snapshotTimestamp() {
+    return new Date()
+        .toISOString()
+        .replace(/\.\d{3}Z$/, '')
+        .replace(/:/g, '-');
+}
+function validateMappings(root, backupsRoot, mappings) {
+    assertUniqueKeys(mappings.map((mapping) => mapping.source));
+    assertUniqueKeys(mappings.map((mapping) => mapping.destination), true);
+    const backupKey = relative(root, backupsRoot).split('\\').join('/').toLowerCase();
+    for (const mapping of mappings) {
+        const sourceKey = mapping.source.toLowerCase();
+        if (sourceKey === backupKey || sourceKey.startsWith(`${backupKey}/`)) {
+            throw new Error(`Snapshot source aliases the backup namespace: ${mapping.source}`);
+        }
+        assertSafeFile(workspacePath(root, mapping.source));
+    }
+}
+function copySnapshotFiles(root, backupDir, mappings) {
+    return mappings.map(({ source, destination }) => {
+        const bytes = readSnapshotBytes(workspacePath(root, source));
+        const target = join(backupDir, destination);
+        mkdirSync(dirname(target), { recursive: true });
+        assertSafeDirectory(dirname(target));
+        writeFileSync(target, bytes, { flag: 'wx', mode: 0o600 });
+        const digest = byteHash(bytes);
+        if (byteHash(readSnapshotBytes(target)) !== digest) {
+            throw new Error(`Snapshot verification failed: ${source}`);
+        }
+        return { source, file: destination, sha256: digest, size: bytes.length };
+    });
+}
+function retainAfterSnapshot(root, backupDir, workspace, limit) {
+    try {
+        return pruneSnapshots(root, backupDir, workspace, limit);
+    }
+    catch (error) {
+        return [`Snapshot completed; retention skipped: ${String(error)}`];
+    }
+}
+function completeSnapshot(backupDir, workspace, timestamp, files, options, githubDir) {
+    const manifest = {
+        format: SNAPSHOT_FORMAT,
+        schemaVersion: 1,
+        status: 'complete',
+        timestamp,
+        completedAt: new Date().toISOString(),
+        packageVersion: options.packageVersion ?? 'unknown',
+        workspaceRoot: workspace,
+        ...(githubDir ? { githubDir } : {}),
+        files,
+    };
+    writeFileSync(join(backupDir, 'manifest.json'), JSON.stringify(manifest, null, 2), {
+        flag: 'wx',
+        mode: 0o600,
+    });
+    recognizedSnapshot(backupDir, workspace);
+}
+/** Internal mapping adapter keeps the legacy .github-relative backup layout. */
+export function createMappedSnapshot(workspaceRoot, devstepsDir, mappings, options = {}, githubDir) {
+    const timestamp = snapshotTimestamp();
+    const empty = { timestamp, fileCount: 0, files: [] };
+    let backupDir = '';
+    let complete = false;
+    let owner;
+    const warnings = [];
+    if (options.skip)
+        return { success: true, backupDir, ...empty };
+    try {
+        const workspace = resolve(workspaceRoot);
+        const backupsRoot = validateBackupsRoot(workspace, devstepsDir);
+        const limit = options.maxBackups ?? 5;
+        if (!Number.isSafeInteger(limit) || limit < 0)
+            throw new Error('Invalid maximum backup count');
+        validateMappings(workspace, backupsRoot, mappings);
+        if (!mappings.length)
+            return { success: true, backupDir, ...empty };
+        mkdirSync(backupsRoot, { recursive: true });
+        assertSafeDirectory(backupsRoot);
+        backupDir = mkdtempSync(join(backupsRoot, `${BACKUP_DIR_PREFIX}${timestamp}-`));
+        owner = pathEntry(backupDir);
+        const files = copySnapshotFiles(workspace, backupDir, mappings);
+        completeSnapshot(backupDir, workspace, timestamp, files, options, githubDir);
+        complete = true;
+        warnings.push(...retainAfterSnapshot(backupsRoot, backupDir, workspace, limit));
+        return {
+            success: true,
+            backupDir,
+            timestamp,
+            fileCount: files.length,
+            files: files.map((entry) => entry.file),
+            ...(warnings.length ? { warnings } : {}),
+        };
+    }
+    catch (error) {
+        if (backupDir && !complete) {
+            try {
+                cleanIncompleteSnapshot(backupDir, owner);
+            }
+            catch (cleanupError) {
+                warnings.push(`Incomplete snapshot preserved: ${String(cleanupError)}`);
+            }
+        }
+        return {
+            success: false,
+            backupDir,
+            ...empty,
+            error: error instanceof Error ? error : new Error(String(error)),
+            ...(warnings.length ? { warnings } : {}),
+        };
+    }
+}
+/** Every input is an existing workspace-relative file with the same backup key. */
+export function createWorkspaceSnapshot(workspaceRoot, devstepsDir, relativeExistingPaths, options) {
+    return createMappedSnapshot(workspaceRoot, devstepsDir, relativeExistingPaths.map((source) => ({ source, destination: source })), options);
+}
+//# sourceMappingURL=agent-files-snapshot.js.map

package/dist/utils/agent-files-snapshot.js.map

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

package/dist/utils/atomic-write.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Atomic file writes.
+ *
+ * Formalises the `.tmp` → `rename` pattern `docs-map.ts` already applies
+ * (ADR-S2-11) so the counters and the derived indexes get the same guarantee.
+ *
+ * The hazard is not concurrency — simultaneous Copilot and Claude Code use is
+ * out of scope by decision — but interruption. A Ctrl-C, a crash, or an editor
+ * reload during a plain `writeFileSync` leaves truncated JSON, and a truncated
+ * index makes every later command fail until `devsteps doctor` repairs it.
+ *
+ * `rename` is atomic within a filesystem, so the temporary file is always
+ * created in the target's own directory rather than in the system temp dir.
+ *
+ * @see EPIC-012 STORY-379 TASK-748
+ */
+/**
+ * Names of the writers' temporary files: `.<pid>.<hex>.tmp` and
+ * `.<pid>.<n>.<hex>.tmp`, plus the older `.<pid>.tmp` and `.<pid>.<n>.tmp`.
+ * `listAttachments` uses it to keep them out of an item's attachments.
+ */
+export declare const ATOMIC_TEMP_NAME: RegExp;
+/**
+ * `renameSync` that retries EPERM, EBUSY and EACCES a bounded number of times with a
+ * growing pause (10 to 100 ms). Any other error is rethrown at once; after the last
+ * attempt the original error is rethrown. Never falls back to a non-atomic write.
+ */
+export declare function renameWithRetrySync(from: string, to: string, beforeRename?: () => void): void;
+/** Async twin of `renameWithRetrySync`, pausing with a timer instead of blocking. */
+export declare function renameWithRetry(from: string, to: string): Promise<void>;
+export interface AtomicWriteOptions {
+    /** Runs before creating or removing the temp file; throwing skips that mutation. */
+    beforeWrite?: () => void;
+    /** Runs before every rename attempt; throwing aborts the write and attempts temp cleanup. */
+    beforeRename?: () => void;
+}
+/**
+ * Write `contents` to `filePath` so a reader observes either the previous
+ * content or the new content, never a partial file.
+ *
+ * The caller is responsible for the target directory existing, matching the
+ * behaviour of the `writeFileSync` calls this replaces.
+ */
+export declare function writeFileAtomic(filePath: string, contents: string, options?: AtomicWriteOptions): void;
+/**
+ * Write bytes or text to `filePath` atomically, like `writeFileAtomic`, with a temp
+ * name that is unique per call (`.<pid>.<n>.<hex>.tmp`) so two writes into one folder
+ * never share a temp file. Used for attachments (STORY-431).
+ */
+export declare function writeBytesAtomic(filePath: string, contents: Uint8Array | string, options?: AtomicWriteOptions): void;
+/** Serialise `value` as pretty-printed JSON and write it atomically. */
+export declare function writeJsonAtomic(filePath: string, value: unknown): void;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/utils/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../src/utils/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAA6C,CAAC;AAgB3E;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAY7F;AAED,qFAAqF;AACrF,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU7E;AAED,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CAEN;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,UAAU,GAAG,MAAM,EAC7B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CAGN;AA2BD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtE"}

package/dist/utils/atomic-write.js

@@ -0,0 +1,129 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Atomic file writes.
+ *
+ * Formalises the `.tmp` → `rename` pattern `docs-map.ts` already applies
+ * (ADR-S2-11) so the counters and the derived indexes get the same guarantee.
+ *
+ * The hazard is not concurrency — simultaneous Copilot and Claude Code use is
+ * out of scope by decision — but interruption. A Ctrl-C, a crash, or an editor
+ * reload during a plain `writeFileSync` leaves truncated JSON, and a truncated
+ * index makes every later command fail until `devsteps doctor` repairs it.
+ *
+ * `rename` is atomic within a filesystem, so the temporary file is always
+ * created in the target's own directory rather than in the system temp dir.
+ *
+ * @see EPIC-012 STORY-379 TASK-748
+ */
+import { randomBytes } from 'node:crypto';
+import { renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Errors a rename raises on Windows while an antivirus scanner, indexer or watcher holds a file. */
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_ATTEMPTS = 8;
+const RENAME_BACKOFF_MIN_MS = 10;
+const RENAME_BACKOFF_MAX_MS = 100;
+/**
+ * Names of the writers' temporary files: `.<pid>.<hex>.tmp` and
+ * `.<pid>.<n>.<hex>.tmp`, plus the older `.<pid>.tmp` and `.<pid>.<n>.tmp`.
+ * `listAttachments` uses it to keep them out of an item's attachments.
+ */
+export const ATOMIC_TEMP_NAME = /^\.\d+(?:\.\d+)?(?:\.[0-9a-f]{8})?\.tmp$/;
+function isTransientRenameError(error) {
+    const code = error?.code;
+    return typeof code === 'string' && TRANSIENT_RENAME_CODES.has(code);
+}
+function backoffMs(attempt) {
+    return Math.min(RENAME_BACKOFF_MAX_MS, RENAME_BACKOFF_MIN_MS * 2 ** (attempt - 1));
+}
+/** Block the thread for `ms` without spinning. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * `renameSync` that retries EPERM, EBUSY and EACCES a bounded number of times with a
+ * growing pause (10 to 100 ms). Any other error is rethrown at once; after the last
+ * attempt the original error is rethrown. Never falls back to a non-atomic write.
+ */
+export function renameWithRetrySync(from, to, beforeRename) {
+    for (let attempt = 1;; attempt++) {
+        // Recheck guarded writes after each backoff. Guard failures abort without retrying.
+        beforeRename?.();
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt >= RENAME_ATTEMPTS || !isTransientRenameError(error))
+                throw error;
+            sleepSync(backoffMs(attempt));
+        }
+    }
+}
+/** Async twin of `renameWithRetrySync`, pausing with a timer instead of blocking. */
+export async function renameWithRetry(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt >= RENAME_ATTEMPTS || !isTransientRenameError(error))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, backoffMs(attempt)));
+        }
+    }
+}
+function randomSuffix() {
+    return randomBytes(4).toString('hex');
+}
+/**
+ * Write `contents` to `filePath` so a reader observes either the previous
+ * content or the new content, never a partial file.
+ *
+ * The caller is responsible for the target directory existing, matching the
+ * behaviour of the `writeFileSync` calls this replaces.
+ */
+export function writeFileAtomic(filePath, contents, options) {
+    writeAtomic(filePath, contents, `.${process.pid}.${randomSuffix()}.tmp`, options);
+}
+let tempCounter = 0;
+/**
+ * Write bytes or text to `filePath` atomically, like `writeFileAtomic`, with a temp
+ * name that is unique per call (`.<pid>.<n>.<hex>.tmp`) so two writes into one folder
+ * never share a temp file. Used for attachments (STORY-431).
+ */
+export function writeBytesAtomic(filePath, contents, options) {
+    tempCounter += 1;
+    writeAtomic(filePath, contents, `.${process.pid}.${tempCounter}.${randomSuffix()}.tmp`, options);
+}
+function writeAtomic(filePath, contents, tmpName, options) {
+    // Same directory as the target: rename is only atomic within one filesystem.
+    const tmpPath = join(dirname(filePath), tmpName);
+    try {
+        options?.beforeWrite?.();
+        if (typeof contents === 'string')
+            writeFileSync(tmpPath, contents, 'utf-8');
+        else
+            writeFileSync(tmpPath, contents);
+        renameWithRetrySync(tmpPath, filePath, options?.beforeRename);
+    }
+    catch (error) {
+        // Remove a failed write's temp only while its caller's mutation guard still passes.
+        try {
+            options?.beforeWrite?.();
+            unlinkSync(tmpPath);
+        }
+        catch {
+            /* the temp was never created, or its original directory is no longer safe to access */
+        }
+        throw error;
+    }
+}
+/** Serialise `value` as pretty-printed JSON and write it atomically. */
+export function writeJsonAtomic(filePath, value) {
+    writeFileAtomic(filePath, JSON.stringify(value, null, 2));
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/utils/atomic-write.js.map

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

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

@@ -2,33 +2,14 @@
  * 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.
+ * Legacy .github backup API backed by complete, uniquely claimed snapshots.
  */
-export interface BackupResult {
-    success: boolean;
-    backupDir: string;
-    timestamp: string;
-    fileCount: number;
-    files: string[];
-    error?: Error;
+import { type BackupResult, type SnapshotOptions } from './agent-files-snapshot.js';
+export type { BackupResult } from './agent-files-snapshot.js';
+export interface BackupOptions extends SnapshotOptions {
+    /** Additional .github-relative retired files, using portable `/` separators. */
+    extraFiles?: string[];
 }
-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.
- */
+/** Preserve valid callers' file selection, relative results and manifest fields. */
 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

@@ -1 +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"}
+{"version":3,"file":"backup-github-files.d.ts","sourceRoot":"","sources":["../../src/utils/backup-github-files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,eAAe,EAErB,MAAM,2BAA2B,CAAC;AAQnC,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAuBD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CA0Bd"}

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

@@ -2,132 +2,55 @@
  * 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.
+ * Legacy .github backup API backed by complete, uniquely claimed snapshots.
  */
+import { readdirSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { createMappedSnapshot, snapshotTimestamp, } from './agent-files-snapshot.js';
+import { assertSafeDirectory, pathEntry, validateSnapshotKey, workspacePath, } from './snapshot-paths.js';
 function collectManagedFiles(githubDir) {
-    const subdirs = ['agents', 'instructions', 'prompts'];
-    const collected = [];
-    for (const sub of subdirs) {
-        const dir = join(githubDir, sub);
-        if (!existsSync(dir))
+    assertSafeDirectory(githubDir, true);
+    const files = [];
+    for (const subdirectory of ['agents', 'instructions', 'prompts']) {
+        const directory = join(githubDir, subdirectory);
+        if (!pathEntry(directory))
             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) });
+        assertSafeDirectory(directory);
+        for (const name of readdirSync(directory)) {
+            if (name.startsWith('devsteps') &&
+                (name.endsWith('.agent.md') ||
+                    name.endsWith('.instructions.md') ||
+                    name.endsWith('.prompt.md'))) {
+                files.push(`${subdirectory}/${name}`);
+            }
         }
     }
-    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 });
-    }
+    return files;
 }
-/**
- * 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.
- */
+/** Preserve valid callers' file selection, relative results and manifest fields. */
 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;
+    const workspace = dirname(resolve(githubDir));
+    if (options?.skip)
+        return createMappedSnapshot(workspace, devstepsDir, [], options, githubDir);
     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);
+        const selected = new Set(collectManagedFiles(githubDir));
+        for (const extra of options?.extraFiles ?? []) {
+            validateSnapshotKey(extra);
+            selected.add(extra);
         }
-        // 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,
-        };
+        const mappings = [...selected].map((destination) => ({
+            source: relative(workspace, workspacePath(resolve(githubDir), destination))
+                .split('\\')
+                .join('/'),
+            destination,
+        }));
+        return createMappedSnapshot(workspace, devstepsDir, mappings, options, githubDir);
     }
     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,
+            backupDir: '',
+            timestamp: snapshotTimestamp(),
             fileCount: 0,
             files: [],
             error: error instanceof Error ? error : new Error(String(error)),

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;CAMxB,CAAC;AAEF;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAoChE;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IA0BrD;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAI5D;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAWrC;;;OAGG;IACH,KAAK,IAAI,UAAU;IAanB;;OAEG;IACH,UAAU,IAAI,IAAI;CAInB;AAKD;;GAEG;AACH,wBAAgB,QAAQ,IAAI,YAAY,CAKvC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB,cAAc;IACd,oBAAoB;IACpB,eAAe;IACf,kBAAkB;IAClB,cAAc;CACf,CAAC;AAEF;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAkC/D;IAED;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAwBpD;IAED;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAE3D;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAIZ;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3B;IAED;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASpC;IAED;;;OAGG;IACH,KAAK,IAAI,UAAU,CAWlB;IAED;;OAEG;IACH,UAAU,IAAI,IAAI,CAGjB;CACF;AAKD;;GAEG;AACH,wBAAgB,QAAQ,IAAI,YAAY,CAKvC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC"}

package/dist/utils/claude-host.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Claude Code host support.
+ *
+ * The Copilot host receives its customization as a `.github` tree copied into
+ * the workspace. Claude Code receives its agents, commands, and skills from the
+ * DevSteps plugin instead, so nothing is copied — but a project can still
+ * anchor the operating contract in its own `CLAUDE.md`.
+ *
+ * That anchor is the *same* managed block the Copilot contract carries: the
+ * block is vendor-neutral prose, so one authored source serves both hosts
+ * (TASK-770). An earlier revision kept a second, shorter body here on the
+ * grounds that the plugin ships the full contract as a skill; that reasoning is
+ * superseded, because a workspace that has not installed the plugin then has no
+ * contract at all, and two bodies drift.
+ *
+ * `.claude/settings.json` is never touched: permissions are the user's security
+ * boundary.
+ *
+ * @see EPIC-053 EPIC-056 TASK-736 TASK-770
+ */
+import { type ContractFileResult, type ContractFileStatus } from './contract-block.js';
+export type ClaudeContractStatus = ContractFileStatus;
+export type ClaudeContractResult = ContractFileResult;
+export interface ClaudeContractOptions {
+    /** Rewrite the block even when the installed one carries local edits. */
+    force?: boolean;
+}
+/**
+ * The project-owned header written above the block when `CLAUDE.md` is created.
+ *
+ * It names the project, says which part of the file DevSteps owns, and points at
+ * the plugin that ships the agents, commands, and skills. Everything here is the
+ * project's from the moment it is written — updates never touch it.
+ */
+export declare function renderClaudeContractPreamble(projectName?: string): string;
+/**
+ * Create or update the DevSteps contract block in a project's `CLAUDE.md`.
+ *
+ * Creates the file with the preamble when it is absent, replaces the block when
+ * it is present, and migrates a workspace that still carries the earlier
+ * `devsteps:claude-contract` delimiters. A locally edited block is left alone
+ * unless `force` is set, mirroring the Copilot payload rule.
+ */
+export declare function writeClaudeContractBlock(projectPath: string, sourceGithubDir: string, projectName?: string, options?: ClaudeContractOptions): ClaudeContractResult;
+//# sourceMappingURL=claude-host.d.ts.map

package/dist/utils/claude-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-host.d.ts","sourceRoot":"","sources":["../../src/utils/claude-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAGxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AACtD,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAEtD,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAezE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CAgBtB"}