bugproof 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to BugProof will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-06
+
+### Added
+
+- **Capture command** — Record failing commands with full context (source code, environment, output)
+- **Replay command** — Execute captured bug artifacts with sandbox isolation and fingerprint matching
+- **Inspect command** — Examine artifact contents without running code
+- **Diff command** — Compare two artifacts side-by-side for changes
+- **Cross-platform support** — Capture on Windows, replay on Linux/macOS with exact fingerprint matching
+- **Sandbox isolation** — Linux cgroups v2, Windows Job Objects, macOS sandbox-exec isolation
+- **Secret redaction** — Automatic detection and masking of 20+ secret patterns (API keys, tokens, passwords)
+- **File association** — Post-install registration of `.bug` file type (Windows/Linux/macOS)
+- **Install-time checks** — Verify Node.js 18+, Git availability, optional language toolchains
+- **JSON output mode** — Structured output for CI/CD integration
+- **Environment override** — Custom environment variables during replay
+- **Exclude patterns** — Skip files matching patterns during capture
+- **Source snapshots** — Bundle git-tracked files with artifacts
+
+### Security
+
+- Path traversal prevention via `isPathWithinBoundary()`
+- Git ref injection prevention via `isValidGitRef()`
+- Shell injection prevention (no shell: true in spawn calls)
+- Environment variable hijacking prevention (LD_PRELOAD, NODE_OPTIONS blocklist)
+- Symlink escape prevention in file operations
+
+### Testing
+
+- 19 test suites with 131 passing tests
+- 60%+ code coverage across all modules
+- Cross-platform validation (Windows ↔ Linux)
+- E2E sandbox isolation tests
+
+### Documentation
+
+- Comprehensive README with quick start guide
+- CLI help command for discoverability
+- Command reference with examples
+- File association setup instructions
+- Troubleshooting and FAQ sections
+
+## [0.2.0] - Planned
+
+- npm global install polish
+- Docker sandbox fallback
+- Web UI for artifact inspection
+- Language-specific dependency detection
+
+## [0.3.0] - Planned
+
+- Artifact cloud storage (push/pull with signing)
+- GitHub issue integration
+- Richer diff visualization
+
+## [0.4.0] - Planned
+
+- Advanced CI/CD integration
+- Enterprise features (audit logging, team sharing)

package/README.md

@@ -0,0 +1,256 @@
+# BugProof
+
+<div align="center">
+
+![BugProof Logo](assets/icon-512x512.png?raw=true&size=200)
+
+**Executable bugs, not bug reports.**
+
+Capture a backend or CLI failure into a portable `.bug` artifact that another machine can replay.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-blue)]()
+[![Cross-Platform](https://img.shields.io/badge/Cross--Platform-Windows%20%7C%20Linux%20%7C%20macOS-blueviolet)]()
+
+</div>
+
+## What BugProof Captures
+
+A `.bug` artifact includes:
+- Source snapshot (git-tracked files, optional untracked)
+- Command, arguments, and working directory
+- Environment schema (secret values redacted)
+- Stdout/stderr and failure fingerprint
+- Capture metadata (OS, architecture, commit, branch)
+
+This makes replay deterministic and shareable.
+
+## Install (NPM Package)
+
+```bash
+npm install -g bugproof
+```
+
+### Install-time checks (automatic)
+
+During installation, BugProof now automatically:
+- Verifies Node.js version (requires 18+)
+- Checks that Git is available
+- Detects optional language toolchains (python/java/gcc/g++/go/rustc)
+- Attempts `.bug` file association and icon registration (best effort, user scope)
+
+If association setup fails on your system, run manual scripts:
+- Windows: `scripts/bugproof-file-association-windows.reg`
+- Linux: `scripts/bugproof-file-association-linux.sh`
+- macOS: `scripts/bugproof-file-association-macos.sh`
+
+## Requirements
+
+Required:
+- Node.js 18+
+- Git
+
+Optional (only needed if your captured command uses them):
+- Python / Java / GCC / G++ / Go / Rust toolchains
+
+## Quick Start
+
+### 1) Capture a failure
+
+```bash
+bugproof capture -- npm test
+```
+
+### 2) Replay it anywhere
+
+```bash
+bugproof replay bug_1778049738215.bug
+```
+
+### 3) Inspect artifact contents
+
+```bash
+bugproof inspect bug_1778049738215.bug
+```
+
+### 4) Diff two artifacts
+
+```bash
+bugproof diff old.bug new.bug
+```
+
+## CLI Help (Lists Everything)
+
+Show full command list and global options:
+
+```bash
+bugproof --help
+```
+
+Show command-specific help:
+
+```bash
+bugproof help capture
+bugproof help replay
+bugproof help inspect
+bugproof help diff
+```
+
+You can also use:
+
+```bash
+bugproof capture --help
+bugproof replay --help
+bugproof inspect --help
+bugproof diff --help
+```
+
+## Commands Reference
+
+### `bugproof capture [command...]`
+
+Capture a command execution as a `.bug` artifact.
+
+Examples:
+
+```bash
+bugproof capture -- npm test
+bugproof capture -n auth-crash -d "Login fails on expired session" -- node server.js
+bugproof capture --include-untracked -- python app.py
+bugproof capture -e "*.log" -e "*.tmp" -- go test ./...
+bugproof capture --timeout 600000 -- java -cp . Main
+bugproof capture --json -- node script.js
+```
+
+Options:
+- `--include-untracked` Include untracked files (`git ls-files -o`)
+- `--skip-secrets` Skip environment secret scan
+- `--timeout <ms>` Command timeout in milliseconds (default: `300000`)
+- `-n, --name <name>` Human-readable artifact name
+- `-d, --description <desc>` Bug description
+- `-e, --exclude <pattern>` Exclude files matching pattern (repeatable)
+- `--json` Structured JSON output
+
+### `bugproof replay <artifact>`
+
+Replay a `.bug` artifact and compare failure signature.
+
+Examples:
+
+```bash
+bugproof replay my-bug.bug
+bugproof replay --version-match strict my-bug.bug
+bugproof replay --version-match branch my-bug.bug
+bugproof replay --sandbox isolated my-bug.bug
+bugproof replay --env API_URL=https://staging.local --env DEBUG=true my-bug.bug
+bugproof replay --json my-bug.bug
+```
+
+Options:
+- `--version-match <mode>` `strict | current | branch` (default: `current`)
+- `--sandbox <level>` `workspace | isolated | full` (default: `workspace`)
+- `--env <var=value>` Override environment variable (repeatable)
+- `--json` Structured JSON output
+
+### `bugproof inspect <artifact>`
+
+Inspect artifact metadata and failure details without replaying.
+
+Examples:
+
+```bash
+bugproof inspect my-bug.bug
+bugproof inspect --json my-bug.bug
+```
+
+Options:
+- `--json` Structured JSON output
+
+### `bugproof diff <left> <right>`
+
+Compare two artifacts side-by-side.
+
+Examples:
+
+```bash
+bugproof diff bug-before.bug bug-after.bug
+bugproof diff --json bug-before.bug bug-after.bug
+```
+
+Options:
+- `--json` Structured JSON output
+
+## File Association and Icon Registration
+
+### Windows
+
+BugProof installer registers `.bug` under:
+- `HKCU\\Software\\Classes\\.bug`
+- `HKCU\\Software\\Classes\\BugProof.Artifact`
+
+with open command pointing to:
+- `node <package>/dist/cli.js replay "%1"`
+
+### Linux
+
+BugProof installer registers:
+- MIME type `application/x-bugproof`
+- `bugproof.desktop` handler
+- User-level icon entry in `~/.local/share/icons/hicolor/...`
+
+### macOS
+
+Installer attempts registration via bundled script. If Finder association does not apply, run:
+
+```bash
+bash scripts/bugproof-file-association-macos.sh
+```
+
+## Cross-Platform Replay Matrix
+
+| Capture \ Replay | Windows | Linux | macOS |
+|---|---|---|---|
+| Windows | Yes | Yes | Yes |
+| Linux | Yes | Yes | Yes |
+| macOS | Yes | Yes | Yes |
+
+Notes:
+- Exit codes may differ by OS for signals/crashes.
+- Fingerprint/error-pattern matching is used for reproduction verdict.
+
+## Legacy Notes (Kept from Old README)
+
+These project principles remain unchanged:
+- Security-first default behavior
+- Language-agnostic command capture
+- Minimal runtime dependencies
+- Reproducibility over screenshots/log snippets
+
+## Roadmap
+
+- [x] v0.1: CLI core (capture/replay/inspect/diff)
+- [x] v0.1: Cross-platform replay support
+- [x] v0.1: Secret redaction and sandbox layers
+- [ ] v0.2: npm global install polish and Docker sandbox fallback
+- [ ] v0.2: Web UI for artifact inspection
+- [ ] v0.3: Artifact push/pull and signing
+- [ ] v0.3: Language-specific dependency detection
+- [ ] v0.4: GitHub issue integration and richer diff visualization
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## CI and Releases
+
+- `push` and `pull_request` CI runs only for core paths such as `src/`, `scripts/`, `tests/`, `package.json`, `tsconfig.json`, and `assets/`.
+- Docs-only edits like `README.md` do not start the CI workflow.
+- Publishing to npmjs.com and GitHub Packages runs only on version tags like `v0.1.0`.
+
+## License
+
+MIT

package/dist/capture/engine.d.ts

@@ -0,0 +1,12 @@
+import { RunConfig } from '../types/artifact.js';
+import { FailureRecord } from '../types/failure.js';
+/**
+ * Spawns the command, captures its output, and produces a FailureRecord.
+ * Uses streaming to handle large output without memory issues.
+ */
+export declare function executeAndCapture(config: RunConfig): Promise<{
+    failure: FailureRecord;
+    stdout: string;
+    stderr: string;
+}>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/capture/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/capture/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAwI9H"}

package/dist/capture/engine.js

@@ -0,0 +1,129 @@
+import { spawn } from 'child_process';
+import { generateExactFingerprint, extractErrorPatterns } from '../utils/fingerprint.js';
+/**
+ * Spawns the command, captures its output, and produces a FailureRecord.
+ * Uses streaming to handle large output without memory issues.
+ */
+export async function executeAndCapture(config) {
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        // Define resolveExecutable first, before using it
+        const resolveExecutable = (cmd) => {
+            const normalized = cmd.trim().toLowerCase();
+            if (normalized === 'node' || normalized === 'node.exe') {
+                return process.execPath;
+            }
+            return cmd;
+        };
+        const command = resolveExecutable(config.command[0]);
+        const args = config.command.slice(1);
+        // We keep strings in memory for v0.1 (in v0.2 this would stream directly to disk)
+        let stdoutBuffer = '';
+        let stderrBuffer = '';
+        let stdoutLines = 0;
+        let stderrLines = 0;
+        // Safety limit to avoid OOM: 1MB per stream
+        const MAX_BUFFER_SIZE = 1024 * 1024;
+        let isTimeout = false;
+        let resolved = false;
+        let proc;
+        const safeResolve = (value) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(value);
+        };
+        try {
+            proc = spawn(command, args, {
+                cwd: config.working_directory,
+                env: config.environment,
+                shell: false // Prevent shell injection
+            });
+        }
+        catch (err) {
+            // Command not found or spawn error
+            const errStr = String(err);
+            safeResolve({
+                failure: {
+                    exit_code: 1,
+                    signal: null,
+                    stdout_lines: 0,
+                    stderr_lines: 1,
+                    stderr_snippet: errStr,
+                    fingerprint: generateExactFingerprint(errStr),
+                    error_patterns: extractErrorPatterns(errStr),
+                    duration_ms: Date.now() - startTime,
+                    timeout: false
+                },
+                stdout: '',
+                stderr: errStr
+            });
+            return;
+        }
+        // Set timeout
+        const timeoutHandle = setTimeout(() => {
+            isTimeout = true;
+            proc.kill('SIGKILL');
+        }, config.timeout_ms);
+        if (config.capture_output) {
+            proc.stdout?.on('data', (data) => {
+                const chunk = data.toString();
+                stdoutLines += (chunk.match(/\n/g) || []).length;
+                if (stdoutBuffer.length < MAX_BUFFER_SIZE) {
+                    stdoutBuffer += chunk;
+                }
+            });
+            proc.stderr?.on('data', (data) => {
+                const chunk = data.toString();
+                stderrLines += (chunk.match(/\n/g) || []).length;
+                if (stderrBuffer.length < MAX_BUFFER_SIZE) {
+                    stderrBuffer += chunk;
+                }
+            });
+        }
+        proc.on('close', (code, signal) => {
+            clearTimeout(timeoutHandle);
+            const duration = Date.now() - startTime;
+            // Determine snippet (last 5 lines of stderr)
+            const lines = stderrBuffer.trim().split('\n');
+            const snippet = lines.slice(Math.max(0, lines.length - 5)).join('\n');
+            const failure = {
+                exit_code: code ?? 1,
+                signal: signal,
+                stdout_lines: stdoutLines,
+                stderr_lines: stderrLines,
+                stderr_snippet: snippet,
+                fingerprint: generateExactFingerprint(stderrBuffer),
+                error_patterns: extractErrorPatterns(stderrBuffer),
+                duration_ms: duration,
+                timeout: isTimeout
+            };
+            safeResolve({
+                failure,
+                stdout: stdoutBuffer,
+                stderr: stderrBuffer
+            });
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timeoutHandle);
+            const errStr = String(err);
+            stderrBuffer += errStr;
+            safeResolve({
+                failure: {
+                    exit_code: 1,
+                    signal: null,
+                    stdout_lines: stdoutLines,
+                    stderr_lines: stderrLines + 1,
+                    stderr_snippet: errStr,
+                    fingerprint: generateExactFingerprint(errStr),
+                    error_patterns: extractErrorPatterns(errStr),
+                    duration_ms: Date.now() - startTime,
+                    timeout: false
+                },
+                stdout: stdoutBuffer,
+                stderr: stderrBuffer
+            });
+        });
+    });
+}
+//# sourceMappingURL=engine.js.map

package/dist/capture/engine.js.map

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

package/dist/capture/packager.d.ts

@@ -0,0 +1,39 @@
+import { ArtifactManifest, EnvSchema, RunConfig, ArtifactMetadata } from '../types/artifact.js';
+import { FailureRecord } from '../types/failure.js';
+export interface PackageOptions {
+    manifest: ArtifactManifest;
+    envSchema: EnvSchema;
+    runConfig: RunConfig;
+    metadata: ArtifactMetadata;
+    failure: FailureRecord;
+    stdout: string;
+    stderr: string;
+    secretKeys: string[];
+    includeUntracked?: boolean;
+    excludePatterns?: string[];
+}
+export interface FileEntry {
+    path: string;
+    size: number;
+    sha256: string;
+}
+/**
+ * Packages the artifact into the .bug directory format specified in DESIGN.md.
+ *
+ * Directory layout:
+ *   manifest.json
+ *   env.schema.json
+ *   metadata.json
+ *   run.json          (environment secrets stripped)
+ *   failure.json
+ *   logs/stdout.txt
+ *   logs/stderr.txt
+ *   logs/fingerprint.json
+ *   files/...          (git-tracked source snapshot)
+ */
+export declare function packageArtifact(artifactPath: string, options: PackageOptions): Promise<{
+    filesCount: number;
+    totalSize: number;
+    fileEntries: FileEntry[];
+}>;
+//# sourceMappingURL=packager.d.ts.map

package/dist/capture/packager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packager.d.ts","sourceRoot":"","sources":["../../src/capture/packager.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,CA6E9E"}

package/dist/capture/packager.js

@@ -0,0 +1,145 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as os from 'os';
+import { spawnSync } from 'child_process';
+import { zipDirectory } from '../utils/archive.js';
+import { filterByExcludePatterns } from '../utils/exclude.js';
+import { isPathWithinBoundary } from '../utils/security.js';
+const MAX_ARTIFACT_SIZE = 50 * 1024 * 1024; // 50MB hard limit per DESIGN.md
+const WARN_THRESHOLD = 10 * 1024 * 1024; // 10MB warning per DESIGN.md
+/**
+ * Packages the artifact into the .bug directory format specified in DESIGN.md.
+ *
+ * Directory layout:
+ *   manifest.json
+ *   env.schema.json
+ *   metadata.json
+ *   run.json          (environment secrets stripped)
+ *   failure.json
+ *   logs/stdout.txt
+ *   logs/stderr.txt
+ *   logs/fingerprint.json
+ *   files/...          (git-tracked source snapshot)
+ */
+export async function packageArtifact(artifactPath, options) {
+    // 1. Create a temporary staging directory
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bugproof-pkg-'));
+    try {
+        // 2. Copy source files first so we can compute counts and checksums
+        const filesDir = path.join(tempDir, 'files');
+        fs.mkdirSync(filesDir, { recursive: true });
+        const fileEntries = copySourceFiles(filesDir, options.runConfig.working_directory, options.includeUntracked ?? false, options.excludePatterns ?? []);
+        const totalSize = fileEntries.reduce((sum, f) => sum + f.size, 0);
+        // 3. Create manifest with actual file stats (immutable: don't mutate input)
+        const manifestWithStats = {
+            ...options.manifest,
+            files_count: fileEntries.length,
+            files_size_bytes: totalSize,
+        };
+        // 4. Build a sanitized RunConfig (strip secret values from environment)
+        const sanitizedEnv = {};
+        for (const [key, val] of Object.entries(options.runConfig.environment)) {
+            if (options.secretKeys.includes(key)) {
+                sanitizedEnv[key] = '<REDACTED>';
+            }
+            else {
+                sanitizedEnv[key] = val;
+            }
+        }
+        const safeRunConfig = { ...options.runConfig, environment: sanitizedEnv };
+        // 5. Write JSON schema files
+        fs.writeFileSync(path.join(tempDir, 'manifest.json'), JSON.stringify(manifestWithStats, null, 2));
+        fs.writeFileSync(path.join(tempDir, 'env.schema.json'), JSON.stringify(options.envSchema, null, 2));
+        fs.writeFileSync(path.join(tempDir, 'metadata.json'), JSON.stringify(options.metadata, null, 2));
+        fs.writeFileSync(path.join(tempDir, 'run.json'), JSON.stringify(safeRunConfig, null, 2));
+        fs.writeFileSync(path.join(tempDir, 'failure.json'), JSON.stringify(options.failure, null, 2));
+        // 6. Write file manifest with checksums
+        fs.writeFileSync(path.join(tempDir, 'files.json'), JSON.stringify(fileEntries, null, 2));
+        // 7. Write logs
+        const logsDir = path.join(tempDir, 'logs');
+        fs.mkdirSync(logsDir, { recursive: true });
+        fs.writeFileSync(path.join(logsDir, 'stdout.txt'), options.stdout);
+        fs.writeFileSync(path.join(logsDir, 'stderr.txt'), options.stderr);
+        fs.writeFileSync(path.join(logsDir, 'fingerprint.json'), JSON.stringify({
+            fingerprint: options.failure.fingerprint,
+            error_patterns: options.failure.error_patterns,
+        }, null, 2));
+        // 8. Compress the temporary directory into the final .bug zip archive
+        await zipDirectory(tempDir, artifactPath);
+        return { filesCount: fileEntries.length, totalSize, fileEntries };
+    }
+    catch (err) {
+        // Cleanup incomplete artifact on failure
+        if (fs.existsSync(artifactPath)) {
+            fs.rmSync(artifactPath, { force: true });
+        }
+        throw err;
+    }
+    finally {
+        // Always clean up the temporary staging directory
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Copy git-tracked files into the artifact, computing SHA-256 checksums per file.
+ */
+function copySourceFiles(filesDir, workingDir, includeUntracked, excludePatterns = []) {
+    const gitArgs = ['ls-files'];
+    if (includeUntracked) {
+        gitArgs.push('-o', '--exclude-standard');
+    }
+    const result = spawnSync('git', gitArgs, { cwd: workingDir, encoding: 'utf-8' });
+    if (result.status !== 0) {
+        throw new Error(`git ls-files failed: ${result.stderr}`);
+    }
+    let relativePaths = result.stdout
+        .split('\n')
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+    // Apply --exclude patterns
+    if (excludePatterns.length > 0) {
+        relativePaths = filterByExcludePatterns(relativePaths, excludePatterns);
+    }
+    const entries = [];
+    let runningSize = 0;
+    for (const relPath of relativePaths) {
+        const sourcePath = path.join(workingDir, relPath);
+        if (!fs.existsSync(sourcePath))
+            continue;
+        // Security: validate path stays within boundaries
+        if (!isPathWithinBoundary(sourcePath, workingDir)) {
+            process.stderr.write(`  Skipping ${relPath}: path traversal detected\n`);
+            continue;
+        }
+        const stats = fs.statSync(sourcePath);
+        if (!stats.isFile())
+            continue;
+        runningSize += stats.size;
+        if (runningSize > MAX_ARTIFACT_SIZE) {
+            throw new Error(`Artifact would exceed the 50 MB limit (currently ${(runningSize / 1024 / 1024).toFixed(1)} MB). ` +
+                'Add large files to .gitignore or use --exclude patterns.');
+        }
+        if (runningSize > WARN_THRESHOLD && entries.length > 0 && entries.length % 50 === 0) {
+            process.stderr.write(`  Warning: artifact is ${(runningSize / 1024 / 1024).toFixed(1)} MB and growing...\n`);
+        }
+        const targetPath = path.join(filesDir, relPath);
+        // Security: validate target path stays within artifact boundary
+        if (!isPathWithinBoundary(targetPath, filesDir)) {
+            process.stderr.write(`  Skipping ${relPath}: target path escapes artifact\n`);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.copyFileSync(sourcePath, targetPath);
+        // Compute SHA-256 checksum
+        const fileBuffer = fs.readFileSync(sourcePath);
+        const hash = crypto.createHash('sha256').update(fileBuffer).digest('hex');
+        entries.push({
+            path: relPath.replace(/\\/g, '/'), // normalize to forward slashes
+            size: stats.size,
+            sha256: hash,
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=packager.js.map