@planu/cli 0.36.0 → 0.38.0

package/dist/engine/reverse-engineer/orchestrator.js

@@ -0,0 +1,200 @@
+// engine/reverse-engineer/orchestrator.ts — AC-7: Parallel analyzer orchestration
+// AC-9: Spec enrichment from analysis results
+// AC-10: Human-readable output summary
+import { analyzeTestCoverage } from './test-analyzer.js';
+import { buildDependencyGraph } from './dependency-graph.js';
+import { detectApiRoutes } from './api-detector.js';
+import { analyzeComplexity } from './complexity-analyzer.js';
+import { analyzeConfig } from './config-analyzer.js';
+const DEFAULT_OPTIONS = {
+    enableTest: true,
+    enableDeps: true,
+    enableApi: true,
+    enableComplexity: true,
+    enableConfig: true,
+};
+export async function runDeepAnalysis(projectPath, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const start = Date.now();
+    // All analyzers are independent — run in parallel
+    const [testCoverage, dependencyGraph, apiRoutes, complexityMetrics, configAnalysis] = await Promise.all([
+        opts.enableTest
+            ? Promise.resolve(analyzeTestCoverage(projectPath))
+            : Promise.resolve(emptyTestCoverage()),
+        opts.enableDeps
+            ? Promise.resolve(buildDependencyGraph(projectPath))
+            : Promise.resolve(emptyDependencyGraph()),
+        opts.enableApi ? Promise.resolve(detectApiRoutes(projectPath)) : Promise.resolve([]),
+        opts.enableComplexity ? Promise.resolve(analyzeComplexity(projectPath)) : Promise.resolve([]),
+        opts.enableConfig
+            ? Promise.resolve(analyzeConfig(projectPath))
+            : Promise.resolve(emptyConfigReport()),
+    ]);
+    return {
+        testCoverage,
+        dependencyGraph,
+        apiRoutes,
+        complexityMetrics,
+        configAnalysis,
+        analysisTimeMs: Date.now() - start,
+    };
+}
+// --- AC-9: Spec enrichment helpers ---
+function detectTags(result) {
+    const tags = [];
+    const tagMap = {
+        jest: 'vitest/jest',
+        vitest: 'vitest/jest',
+        'next.config': 'nextjs',
+        'vite.config': 'vite',
+        tsconfig: 'typescript',
+        docker: 'docker',
+        Docker: 'docker',
+    };
+    for (const cfg of result.configAnalysis.configFiles) {
+        for (const [key, tag] of Object.entries(tagMap)) {
+            if (cfg.includes(key)) {
+                tags.push(tag);
+            }
+        }
+    }
+    if (result.apiRoutes.length > 0) {
+        const methods = new Set(result.apiRoutes.map((r) => r.method));
+        if (methods.has('GET') && methods.has('POST')) {
+            tags.push('rest-api');
+        }
+    }
+    if (result.testCoverage.testedModules.length > 0) {
+        tags.push('has-tests');
+    }
+    return [...new Set(tags)];
+}
+function detectTechDebt(result) {
+    const items = [];
+    if (result.testCoverage.untestedModules.length > 0) {
+        items.push({
+            file: 'multiple files',
+            type: 'missing-tests',
+            description: `${result.testCoverage.untestedModules.length} modules without tests`,
+            severity: result.testCoverage.untestedModules.length > 10 ? 'high' : 'medium',
+            effort: 'large',
+            suggestion: 'Add tests for untested modules to improve coverage',
+        });
+    }
+    if (result.dependencyGraph.cycles.length > 0) {
+        items.push({
+            file: 'dependency graph',
+            type: 'anti-pattern',
+            description: `${result.dependencyGraph.cycles.length} circular dependency cycle(s) detected`,
+            severity: 'high',
+            effort: 'medium',
+            suggestion: 'Break circular dependencies by extracting shared interfaces',
+        });
+    }
+    const hotspots = result.complexityMetrics
+        .flatMap((m) => m.hotspots.map((h) => ({ ...h, file: m.file })))
+        .sort((a, b) => b.complexity - a.complexity)
+        .slice(0, 5);
+    if (hotspots.length > 0) {
+        items.push({
+            file: hotspots[0]?.file ?? 'unknown',
+            type: 'code-smell',
+            description: `${hotspots.length} high-complexity functions (top: ${hotspots[0]?.name} at ${hotspots[0]?.complexity})`,
+            severity: 'medium',
+            effort: 'medium',
+            suggestion: 'Refactor complex functions into smaller, focused units',
+        });
+    }
+    return items;
+}
+export function enrichSpecFromAnalysis(result) {
+    const affectedFiles = result.dependencyGraph.nodes
+        .slice()
+        .sort((a, b) => b.fanIn - a.fanIn)
+        .slice(0, 50)
+        .map((n) => n.file);
+    return { affectedFiles, tags: detectTags(result), techDebt: detectTechDebt(result) };
+}
+// --- AC-10: Output summary ---
+function buildHealthLines(result) {
+    const lines = ['', '## Health Indicators'];
+    const { testCoverage } = result;
+    const total = testCoverage.testedModules.length + testCoverage.untestedModules.length;
+    const coveragePct = total > 0 ? Math.round((testCoverage.testedModules.length / total) * 100) : 0;
+    lines.push(`- Test coverage: ${coveragePct}% (${testCoverage.testedModules.length}/${total} modules)`);
+    lines.push(`- Circular dependencies: ${result.dependencyGraph.cycles.length}`);
+    if (result.complexityMetrics.length > 0) {
+        const avg = result.complexityMetrics.reduce((s, m) => s + m.avgComplexity, 0) /
+            result.complexityMetrics.length;
+        lines.push(`- Average complexity: ${avg.toFixed(1)}`);
+    }
+    lines.push(`- Config files: ${result.configAnalysis.configFiles.length}`);
+    lines.push(`- Environment variables: ${result.configAnalysis.envVars.length}`);
+    return lines;
+}
+export function generateAnalysisSummary(result) {
+    const lines = ['## Architecture Overview'];
+    const { nodes, hubs: hubList, orphans: orphanList } = result.dependencyGraph;
+    lines.push(`- ${nodes.length} modules analyzed, ${hubList.length} hub(s), ${orphanList.length} orphan(s)`);
+    if (result.apiRoutes.length > 0) {
+        const resources = [...new Set(result.apiRoutes.map((r) => r.resource))];
+        lines.push(`- ${result.apiRoutes.length} API routes across ${resources.length} resource(s): ${resources.slice(0, 5).join(', ')}`);
+    }
+    if (result.configAnalysis.infrastructure.length > 0) {
+        lines.push(`- Infrastructure: ${result.configAnalysis.infrastructure.join(', ')}`);
+    }
+    lines.push(...buildHealthLines(result));
+    // Top 5 risk areas
+    lines.push('');
+    lines.push('## Top 5 Risk Areas');
+    const riskAreas = result.complexityMetrics
+        .map((m) => ({
+        file: m.file,
+        complexity: m.avgComplexity,
+        maxFnLen: m.maxFunctionLength,
+        hasCoverage: result.testCoverage.testedModules.some((t) => m.file.includes(t) || t.includes(m.file)),
+    }))
+        .sort((a, b) => {
+        const scoreA = a.complexity * (a.hasCoverage ? 1 : 2);
+        const scoreB = b.complexity * (b.hasCoverage ? 1 : 2);
+        return scoreB - scoreA;
+    })
+        .slice(0, 5);
+    if (riskAreas.length === 0) {
+        lines.push('- No significant risk areas detected');
+    }
+    else {
+        for (const area of riskAreas) {
+            const coverageLabel = area.hasCoverage ? 'tested' : 'UNTESTED';
+            lines.push(`- **${area.file}**: complexity ${area.complexity.toFixed(1)}, max fn ${area.maxFnLen}L [${coverageLabel}]`);
+        }
+    }
+    // Suggested decomposition
+    lines.push('');
+    lines.push('## Suggested Spec Decomposition');
+    const hubs = result.dependencyGraph.hubs;
+    if (hubs.length > 0) {
+        lines.push(`- Hub modules (high fan-in) suggest natural spec boundaries: ${hubs.slice(0, 5).join(', ')}`);
+    }
+    if (result.apiRoutes.length > 0) {
+        const resources = [...new Set(result.apiRoutes.map((r) => r.resource))];
+        lines.push(`- API resources can be separate specs: ${resources.slice(0, 5).join(', ')}`);
+    }
+    if (result.dependencyGraph.orphans.length > 0) {
+        lines.push(`- Orphan modules (no dependents) are safe to refactor independently: ${result.dependencyGraph.orphans.slice(0, 5).join(', ')}`);
+    }
+    lines.push('');
+    lines.push(`*Analysis completed in ${result.analysisTimeMs}ms*`);
+    return lines.join('\n');
+}
+// --- Empty defaults ---
+function emptyTestCoverage() {
+    return { testedModules: [], untestedModules: [], testToSourceRatio: 0 };
+}
+function emptyDependencyGraph() {
+    return { nodes: [], cycles: [], hubs: [], orphans: [] };
+}
+function emptyConfigReport() {
+    return { configFiles: [], envVars: [], featureFlags: [], infrastructure: [] };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/engine/reverse-engineer/orchestrator.js.map

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

package/dist/engine/reverse-engineer/test-analyzer.d.ts

@@ -0,0 +1,4 @@
+import type { TestCoverageReport } from '../../types/reverse-engineer.js';
+export declare function isTestFile(filePath: string): boolean;
+export declare function analyzeTestCoverage(rootDir: string): TestCoverageReport;
+//# sourceMappingURL=test-analyzer.d.ts.map

package/dist/engine/reverse-engineer/test-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-analyzer.d.ts","sourceRoot":"","sources":["../../../src/engine/reverse-engineer/test-analyzer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AA2C1E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOpD;AAiED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAgCvE"}

package/dist/engine/reverse-engineer/test-analyzer.js

@@ -0,0 +1,130 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const TEST_PATTERNS = [
+    /\.test\.\w+$/,
+    /\.spec\.\w+$/,
+    /_test\.\w+$/, // Go convention
+    /Test\.java$/, // JUnit convention
+];
+const TEST_DIRS = new Set(['__tests__', 'test', 'tests', 'spec', 'specs']);
+const SOURCE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.py',
+    '.go',
+    '.java',
+    '.kt',
+    '.rs',
+    '.rb',
+    '.cs',
+    '.cpp',
+    '.c',
+    '.swift',
+]);
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.nuxt',
+    'coverage',
+    'vendor',
+    '__pycache__',
+]);
+export function isTestFile(filePath) {
+    const basename = path.basename(filePath);
+    if (TEST_PATTERNS.some((p) => p.test(basename))) {
+        return true;
+    }
+    const parts = filePath.split(path.sep);
+    return parts.some((p) => TEST_DIRS.has(p));
+}
+function collectFiles(dir) {
+    const results = [];
+    const queue = [dir];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (!current) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (IGNORE_DIRS.has(entry.name)) {
+                continue;
+            }
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(full);
+            }
+            else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+                results.push(full);
+            }
+        }
+    }
+    return results;
+}
+function mapTestToSource(testFile, sourceFiles, rootDir) {
+    const relative = path.relative(rootDir, testFile);
+    // Strip test dir prefix (tests/, test/, __tests__/)
+    const stripped = relative
+        .replace(/^(?:tests?|__tests__|specs?)[/\\]/, '')
+        .replace(/\.(?:test|spec)\./, '.')
+        .replace(/_test\./, '.')
+        .replace(/Test\.java$/, '.java');
+    // Try exact match
+    for (const src of sourceFiles) {
+        const srcRel = path.relative(rootDir, src);
+        if (srcRel === stripped) {
+            return srcRel;
+        }
+    }
+    // Try basename match
+    const targetBase = path.basename(stripped, path.extname(stripped));
+    for (const src of sourceFiles) {
+        const srcBase = path.basename(src, path.extname(src));
+        if (srcBase === targetBase) {
+            return path.relative(rootDir, src);
+        }
+    }
+    return undefined;
+}
+export function analyzeTestCoverage(rootDir) {
+    const allFiles = collectFiles(rootDir);
+    const testFiles = [];
+    const sourceFiles = [];
+    for (const f of allFiles) {
+        if (isTestFile(f)) {
+            testFiles.push(f);
+        }
+        else {
+            sourceFiles.push(f);
+        }
+    }
+    const testedSet = new Set();
+    for (const tf of testFiles) {
+        const mapped = mapTestToSource(tf, sourceFiles, rootDir);
+        if (mapped) {
+            testedSet.add(mapped);
+        }
+    }
+    const testedModules = [...testedSet].sort();
+    const untestedModules = sourceFiles
+        .map((f) => path.relative(rootDir, f))
+        .filter((f) => !testedSet.has(f))
+        .sort();
+    const testToSourceRatio = sourceFiles.length > 0 ? Math.round((testFiles.length / sourceFiles.length) * 100) / 100 : 0;
+    return { testedModules, untestedModules, testToSourceRatio };
+}
+//# sourceMappingURL=test-analyzer.js.map

package/dist/engine/reverse-engineer/test-analyzer.js.map

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

package/dist/engine/safety/atomic-writer.d.ts

@@ -0,0 +1,22 @@
+import type { WriteOptions } from '../../types/safety.js';
+/**
+ * Write JSON data atomically with backup rotation.
+ *
+ * 1. Rotate existing backups (if target exists).
+ * 2. Write to a `.tmp` sibling file.
+ * 3. Optionally verify the `.tmp` contents parse correctly.
+ * 4. Atomically rename `.tmp` to the target path.
+ *
+ * On failure during steps 2-4, the `.tmp` file is cleaned up silently.
+ */
+export declare function writeJsonSafe(filePath: string, data: unknown, opts?: WriteOptions): Promise<void>;
+/**
+ * Attempt to recover a file from its most recent backup.
+ *
+ * Checks `.bak.1`, `.bak.2`, `.bak.3` in order and copies the first
+ * one found back to the target path.
+ *
+ * @returns `true` if recovery succeeded, `false` if no backup exists.
+ */
+export declare function recoverFromBackup(filePath: string, backupCount?: number): Promise<boolean>;
+//# sourceMappingURL=atomic-writer.d.ts.map

package/dist/engine/safety/atomic-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-writer.d.ts","sourceRoot":"","sources":["../../../src/engine/safety/atomic-writer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1D;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAsCf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,SAAuB,GACjC,OAAO,CAAC,OAAO,CAAC,CASlB"}

package/dist/engine/safety/atomic-writer.js

@@ -0,0 +1,89 @@
+// atomic-writer.ts — Atomic JSON writes with backup rotation (SPEC-094 AC-1)
+import { rename, copyFile, unlink, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+const DEFAULT_BACKUP_COUNT = 3;
+/**
+ * Write JSON data atomically with backup rotation.
+ *
+ * 1. Rotate existing backups (if target exists).
+ * 2. Write to a `.tmp` sibling file.
+ * 3. Optionally verify the `.tmp` contents parse correctly.
+ * 4. Atomically rename `.tmp` to the target path.
+ *
+ * On failure during steps 2-4, the `.tmp` file is cleaned up silently.
+ */
+export async function writeJsonSafe(filePath, data, opts) {
+    const backupCount = opts?.backupCount ?? DEFAULT_BACKUP_COUNT;
+    const verify = opts?.verify ?? true;
+    const tmpPath = `${filePath}.tmp`;
+    // Ensure parent directory exists
+    await mkdir(dirname(filePath), { recursive: true });
+    // Rotate backups if target already exists
+    if (existsSync(filePath)) {
+        await rotateBackups(filePath, backupCount);
+        await copyFile(filePath, `${filePath}.bak.1`);
+    }
+    // Serialize
+    const json = JSON.stringify(data, null, 2);
+    try {
+        // Write to temp file
+        await writeFile(tmpPath, json, 'utf-8');
+        // Verify round-trip if requested
+        if (verify) {
+            const readBack = await readFile(tmpPath, 'utf-8');
+            JSON.parse(readBack);
+        }
+        // Atomic rename
+        await rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Cleanup temp file silently
+        try {
+            await unlink(tmpPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw err;
+    }
+}
+/**
+ * Attempt to recover a file from its most recent backup.
+ *
+ * Checks `.bak.1`, `.bak.2`, `.bak.3` in order and copies the first
+ * one found back to the target path.
+ *
+ * @returns `true` if recovery succeeded, `false` if no backup exists.
+ */
+export async function recoverFromBackup(filePath, backupCount = DEFAULT_BACKUP_COUNT) {
+    for (let i = 1; i <= backupCount; i++) {
+        const bakPath = `${filePath}.bak.${i}`;
+        if (existsSync(bakPath)) {
+            await copyFile(bakPath, filePath);
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Rotate backup files: `.bak.{count-1}` -> `.bak.{count}`, etc.
+ *
+ * The oldest backup (`.bak.{count}`) is discarded if it exists.
+ */
+async function rotateBackups(filePath, count) {
+    // Delete the oldest if it exists
+    const oldestPath = `${filePath}.bak.${count}`;
+    if (existsSync(oldestPath)) {
+        await unlink(oldestPath);
+    }
+    // Shift each backup up by one
+    for (let i = count - 1; i >= 1; i--) {
+        const src = `${filePath}.bak.${i}`;
+        const dst = `${filePath}.bak.${i + 1}`;
+        if (existsSync(src)) {
+            await rename(src, dst);
+        }
+    }
+}
+//# sourceMappingURL=atomic-writer.js.map

package/dist/engine/safety/atomic-writer.js.map

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

package/dist/engine/safety/circuit-breaker.d.ts

@@ -0,0 +1,14 @@
+import type { CircuitState, SafetyCircuitConfig } from '../../types/safety.js';
+export declare class CircuitBreaker {
+    private readonly name;
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private readonly config;
+    constructor(name: string, config?: Partial<SafetyCircuitConfig>);
+    execute<T>(fn: () => Promise<T>, fallback?: T): Promise<T>;
+    getState(): CircuitState;
+    reset(): void;
+    getFailureCount(): number;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/engine/safety/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/engine/safety/circuit-breaker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAQ/E,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAE3C,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAKzD,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqChE,QAAQ,IAAI,YAAY;IAIxB,KAAK,IAAI,IAAI;IAKb,eAAe,IAAI,MAAM;CAG1B"}

package/dist/engine/safety/circuit-breaker.js

@@ -0,0 +1,63 @@
+// SPEC-094 AC-5: Circuit breaker for storage operations
+const DEFAULT_CONFIG = {
+    maxFailures: 3,
+    resetTimeoutMs: 60_000,
+    halfOpenMax: 1,
+};
+export class CircuitBreaker {
+    name;
+    state = 'closed';
+    failureCount = 0;
+    lastFailureTime = 0;
+    config;
+    constructor(name, config) {
+        this.name = name;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    async execute(fn, fallback) {
+        if (this.state === 'open') {
+            const elapsed = Date.now() - this.lastFailureTime;
+            if (elapsed >= this.config.resetTimeoutMs) {
+                this.state = 'half-open';
+            }
+            else {
+                if (fallback !== undefined) {
+                    return fallback;
+                }
+                throw new Error(`Circuit open for ${this.name}`);
+            }
+        }
+        const wasHalfOpen = this.state === 'half-open';
+        try {
+            const result = await fn();
+            this.state = 'closed';
+            this.failureCount = 0;
+            return result;
+        }
+        catch (error) {
+            this.failureCount++;
+            this.lastFailureTime = Date.now();
+            if (wasHalfOpen) {
+                this.state = 'open';
+            }
+            else if (this.failureCount >= this.config.maxFailures) {
+                this.state = 'open';
+            }
+            if (fallback !== undefined) {
+                return fallback;
+            }
+            throw error;
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    reset() {
+        this.state = 'closed';
+        this.failureCount = 0;
+    }
+    getFailureCount() {
+        return this.failureCount;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/engine/safety/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../../src/engine/safety/circuit-breaker.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAIxD,MAAM,cAAc,GAAkC;IACpD,WAAW,EAAE,CAAC;IACd,cAAc,EAAE,MAAM;IACtB,WAAW,EAAE,CAAC;CACf,CAAC;AAEF,MAAM,OAAO,cAAc;IACR,IAAI,CAAS;IACtB,KAAK,GAAiB,QAAQ,CAAC;IAC/B,YAAY,GAAG,CAAC,CAAC;IACjB,eAAe,GAAG,CAAC,CAAC;IACX,MAAM,CAAgC;IAEvD,YAAY,IAAY,EAAE,MAAqC;QAC7D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,EAAoB,EAAE,QAAY;QACjD,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC;YAClD,IAAI,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;gBAC1C,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,OAAO,QAAQ,CAAC;gBAClB,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,KAAK,WAAW,CAAC;QAE/C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;YACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAElC,IAAI,WAAW,EAAE,CAAC;gBAChB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACtB,CAAC;iBAAM,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;gBACxD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACtB,CAAC;YAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/engine/safety/file-mutex.d.ts

@@ -0,0 +1,13 @@
+import type { LockHandle } from '../../types/safety.js';
+/**
+ * Acquires a file-based lock for a named resource.
+ * Polls until the lock is available or timeout expires.
+ * Stale locks (old timestamp or dead PID) are auto-released.
+ */
+export declare function acquireLock(resource: string, timeoutMs?: number): Promise<LockHandle>;
+/**
+ * Releases a previously acquired lock.
+ * No-op if the lock file was already removed.
+ */
+export declare function releaseLock(handle: LockHandle): Promise<void>;
+//# sourceMappingURL=file-mutex.d.ts.map

package/dist/engine/safety/file-mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-mutex.d.ts","sourceRoot":"","sources":["../../../src/engine/safety/file-mutex.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,uBAAuB,CAAC;AA4CzE;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,UAAU,CAAC,CAoDrB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnE"}