@planu/cli 4.13.0 → 5.0.0

package/dist/engine/coverage-gap-analyzer.js

@@ -1,3 +1,4 @@
+import { technologyValue } from './technology-registry.js';
 // engine/coverage-gap-analyzer.ts — SPEC-323
 // Maps spec acceptance criteria to existing test files and surfaces untested ACs.
 import { readFile } from 'node:fs/promises';
@@ -14,7 +15,15 @@ const RISK_DOMAIN_MAP = [
         level: 'high',
     },
     {
-        keywords: ['payment', 'billing', 'charge', 'invoice', 'stripe', 'refund', 'subscription'],
+        keywords: [
+            'payment',
+            'billing',
+            'charge',
+            'invoice',
+            technologyValue('technology-stripe-2bed20'),
+            'refund',
+            'subscription',
+        ],
         domain: 'payment',
         level: 'high',
     },

package/dist/engine/crash-shield/detectors/framework-detector.d.ts

@@ -1,3 +1,5 @@
 import type { CrashDetector } from '../../../types/safety-scanner.js';
+import type { CrashShieldFrameworkRule } from '../../../types/crash-shield-framework-rules.js';
+export declare function parseFrameworkRules(value: unknown): CrashShieldFrameworkRule[];
 export declare const frameworkDetector: CrashDetector;
 //# sourceMappingURL=framework-detector.d.ts.map

package/dist/engine/crash-shield/detectors/framework-detector.js

@@ -1,219 +1,137 @@
-// Next.js: getServerSideProps without try/catch
-const NEXT_GSP = /export\s+(?:const|async\s+function|function)\s+getServerSideProps/;
-const HAS_TRY = /\btry\s*\{/;
-// Express: async route handler without error handling
-const EXPRESS_ASYNC_ROUTE = /(?:app|router)\.\w+\s*\([^,)]+,\s*async\s*(?:\([^)]*\)|[a-z]+)\s*=>/;
-const HAS_CATCH_OR_NEXT = /(?:\.catch\s*\(|next\s*\(\s*(?:err|error)|\btry\s*\{)/;
-// Prisma: findUnique/findFirst without null check
-const PRISMA_FIND = /await\s+\w+\.\w+\.(?:findUnique|findFirst)\s*\(/;
-// Matches: if (!result), if (result === null), if (result !== null), result ?? fallback
-const PRISMA_NULL_CHECK = /(?:if\s*\(\s*!\s*\w+|if\s*\(\s*\w+\s*(?:===|!==)\s*null|\?\?)/;
-// Django: Model.objects.get() without DoesNotExist handler
-const DJANGO_OBJECTS_GET = /\w+\.objects\.get\s*\(/;
-// Gin: ShouldBindJSON with ignored error
-const GIN_BIND = /\.ShouldBindJSON\s*\(&?\w+\)/;
-const GIN_BIND_ERROR_HANDLED = /(?:if\s+err\s*!=\s*nil|if\s+\w+\s*:?=\s*.*ShouldBind)/;
-// Actix: unwrap in request handler function
-const ACTIX_HANDLER = /(?:async\s+fn\s+\w+\s*\([^)]*(?:HttpRequest|web::Data|web::Json|web::Path)[^)]*\))/;
-function splitLines(content) {
-    return content.split('\n');
+// engine/crash-shield/detectors/framework-detector.ts — data-driven crash rules (SPEC-442/597)
+import frameworkRulesJson from '../../../config/crash-shield-framework-rules.json' with { type: 'json' };
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
 }
-function isNextJsFile(filePath, content) {
-    return (filePath.endsWith('.tsx') ||
-        filePath.endsWith('.jsx') ||
-        content.includes('next/') ||
-        content.includes("from 'next"));
+function isNonNegativeInteger(value) {
+    return value === undefined || (Number.isInteger(value) && Number(value) >= 0);
 }
-function isExpressFile(content) {
-    return content.includes("from 'express'") || content.includes("require('express')");
-}
-function isPrismaFile(content) {
-    return content.includes('@prisma/client') || content.includes('PrismaClient');
-}
-function isDjangoFile(filePath, content) {
-    return (filePath.endsWith('.py') &&
-        (content.includes('from django') || content.includes('import django')));
-}
-function isGinFile(content) {
-    return content.includes('"github.com/gin-gonic/gin"');
-}
-function isActixFile(content) {
-    return content.includes('actix_web') || content.includes('use actix_web');
-}
-function detectNextJs(filePath, content) {
-    const risks = [];
-    if (!isNextJsFile(filePath, content) || !NEXT_GSP.test(content)) {
-        return risks;
+function hasValidGuard(value) {
+    if (value === undefined) {
+        return true;
     }
-    // Find the function and check if it has try/catch
-    if (!HAS_TRY.test(content)) {
-        const lines = splitLines(content);
-        for (let i = 0; i < lines.length; i++) {
-            if (NEXT_GSP.test(lines[i] ?? '')) {
-                risks.push({
-                    file: filePath,
-                    line: i + 1,
-                    pattern: 'NEXTJS_GSP_NO_TRY',
-                    severity: 'HIGH',
-                    description: 'getServerSideProps without try/catch. Any uncaught error will crash the entire page render.',
-                    suggestedFix: 'Wrap the body of getServerSideProps in try/catch and return { notFound: true } or redirect on error.',
-                    autoFixable: false,
-                });
-            }
-        }
+    if (typeof value !== 'object' || value === null) {
+        return false;
     }
-    return risks;
+    const guard = value;
+    return (['file', 'line', 'window'].includes(String(guard.scope)) &&
+        isStringArray(guard.patterns) &&
+        isNonNegativeInteger(guard.before) &&
+        isNonNegativeInteger(guard.after));
 }
-function detectExpress(filePath, content) {
-    const risks = [];
-    if (!isExpressFile(content)) {
-        return risks;
-    }
-    const lines = splitLines(content);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (EXPRESS_ASYNC_ROUTE.test(line) && !HAS_CATCH_OR_NEXT.test(content)) {
-            risks.push({
-                file: filePath,
-                line: i + 1,
-                pattern: 'EXPRESS_ASYNC_ROUTE_NO_ERROR_HANDLER',
-                severity: 'HIGH',
-                description: 'Async Express route handler without .catch() or next(err). Unhandled promise rejections crash the server in Node.js.',
-                suggestedFix: 'Add .catch(next) at the end, wrap in try/catch and call next(err), or use an async wrapper like express-async-errors.',
-                autoFixable: false,
-            });
+function hasValidPatterns(rule) {
+    try {
+        for (const pattern of [
+            rule.finding,
+            ...rule.contentAny,
+            ...(rule.contentAll ?? []),
+            ...(rule.guard?.patterns ?? []),
+        ]) {
+            new RegExp(pattern, 'i');
         }
+        return true;
+    }
+    catch {
+        return false;
     }
-    return risks;
 }
-function detectPrisma(filePath, content) {
-    const risks = [];
-    if (!isPrismaFile(content)) {
-        return risks;
+export function parseFrameworkRules(value) {
+    if (typeof value !== 'object' ||
+        value === null ||
+        !('rules' in value) ||
+        !('schemaVersion' in value) ||
+        value.schemaVersion !== 1) {
+        throw new Error('[Planu] Invalid crash-shield framework rule catalog.');
     }
-    const lines = splitLines(content);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (PRISMA_FIND.test(line)) {
-            // Check surrounding lines for null check
-            const windowStart = Math.max(0, i - 1);
-            const windowEnd = Math.min(lines.length - 1, i + 5);
-            let hasNullCheck = false;
-            for (let j = windowStart; j <= windowEnd; j++) {
-                if (PRISMA_NULL_CHECK.test(lines[j] ?? '')) {
-                    hasNullCheck = true;
-                    break;
-                }
-            }
-            if (!hasNullCheck) {
-                risks.push({
-                    file: filePath,
-                    line: i + 1,
-                    pattern: 'PRISMA_FIND_NO_NULL_CHECK',
-                    severity: 'HIGH',
-                    description: 'Prisma findUnique/findFirst can return null when record is not found. Accessing fields without null check crashes.',
-                    suggestedFix: 'Check for null: if (!result) { throw new NotFoundError() } or use findUniqueOrThrow().',
-                    autoFixable: false,
-                });
-            }
-        }
+    const rules = value.rules;
+    if (!Array.isArray(rules)) {
+        throw new Error('[Planu] Crash-shield framework rules must be an array.');
     }
-    return risks;
+    return rules.map((candidate) => {
+        if (typeof candidate !== 'object' || candidate === null) {
+            throw new Error('[Planu] Invalid crash-shield framework rule entry.');
+        }
+        const rule = candidate;
+        if (typeof rule.id !== 'string' ||
+            typeof rule.framework !== 'string' ||
+            !isStringArray(rule.fileExtensions) ||
+            !isStringArray(rule.contentAny) ||
+            (rule.contentAll !== undefined && !isStringArray(rule.contentAll)) ||
+            !hasValidGuard(rule.guard) ||
+            typeof rule.finding !== 'string' ||
+            typeof rule.pattern !== 'string' ||
+            typeof rule.description !== 'string' ||
+            typeof rule.suggestedFix !== 'string' ||
+            !['content', 'file-and-content', 'file-or-content'].includes(rule.activationMode ?? '') ||
+            !['HIGH', 'CRITICAL'].includes(rule.severity ?? '')) {
+            throw new Error(`[Planu] Invalid crash-shield framework rule: ${rule.id ?? 'unknown'}.`);
+        }
+        const parsedRule = rule;
+        if (!hasValidPatterns(parsedRule)) {
+            throw new Error(`[Planu] Invalid regex in crash-shield framework rule: ${parsedRule.id}.`);
+        }
+        return parsedRule;
+    });
 }
-function detectDjango(filePath, content) {
-    const risks = [];
-    if (!isDjangoFile(filePath, content)) {
-        return risks;
+const rules = parseFrameworkRules(frameworkRulesJson);
+function matches(pattern, content) {
+    return new RegExp(pattern, 'i').test(content);
+}
+function isActive(rule, filePath, content) {
+    const fileMatch = rule.fileExtensions.some((extension) => filePath.endsWith(extension));
+    const contentMatch = rule.contentAny.some((pattern) => matches(pattern, content));
+    const allContentMatch = (rule.contentAll ?? []).every((pattern) => matches(pattern, content));
+    if (!allContentMatch) {
+        return false;
     }
-    const lines = splitLines(content);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (DJANGO_OBJECTS_GET.test(line) && !content.includes('DoesNotExist')) {
-            risks.push({
-                file: filePath,
-                line: i + 1,
-                pattern: 'DJANGO_GET_NO_DOES_NOT_EXIST',
-                severity: 'HIGH',
-                description: 'Model.objects.get() raises DoesNotExist exception if no record matches. Not catching it crashes the view.',
-                suggestedFix: 'Use try/except Model.DoesNotExist, or use get_object_or_404(), or filter().first().',
-                autoFixable: false,
-            });
-        }
+    if (rule.activationMode === 'file-and-content') {
+        return fileMatch && contentMatch;
     }
-    return risks;
+    if (rule.activationMode === 'file-or-content') {
+        return fileMatch || contentMatch;
+    }
+    return contentMatch;
 }
-function detectGin(filePath, content) {
-    const risks = [];
-    if (!isGinFile(content)) {
-        return risks;
+function isGuarded(rule, lines, lineIndex, content) {
+    if (!rule.guard) {
+        return false;
     }
-    const lines = splitLines(content);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (GIN_BIND.test(line) && !GIN_BIND_ERROR_HANDLED.test(line)) {
-            // Check nearby lines for error handling
-            const windowStart = Math.max(0, i - 1);
-            const windowEnd = Math.min(lines.length - 1, i + 3);
-            let handled = false;
-            for (let j = windowStart; j <= windowEnd; j++) {
-                if (/if\s+err\s*!=\s*nil/.test(lines[j] ?? '')) {
-                    handled = true;
-                    break;
-                }
-            }
-            if (!handled) {
-                risks.push({
-                    file: filePath,
-                    line: i + 1,
-                    pattern: 'GIN_BIND_ERROR_IGNORED',
-                    severity: 'HIGH',
-                    description: 'Gin ShouldBindJSON error not checked. Binding failures are silently ignored, leading to zero-value structs.',
-                    suggestedFix: 'Check the error: if err := c.ShouldBindJSON(&input); err != nil { c.JSON(400, gin.H{"error": err.Error()}); return }',
-                    autoFixable: false,
-                });
-            }
-        }
+    if (rule.guard.scope === 'file') {
+        return rule.guard.patterns.some((pattern) => matches(pattern, content));
     }
-    return risks;
+    const before = rule.guard.scope === 'line' ? 0 : (rule.guard.before ?? 0);
+    const after = rule.guard.scope === 'line' ? 0 : (rule.guard.after ?? 0);
+    const window = lines.slice(Math.max(0, lineIndex - before), lineIndex + after + 1).join('\n');
+    return rule.guard.patterns.some((pattern) => matches(pattern, window));
 }
-function detectActix(filePath, content) {
-    const risks = [];
-    if (!isActixFile(content) || !filePath.endsWith('.rs')) {
-        return risks;
-    }
-    if (!ACTIX_HANDLER.test(content) || !content.includes('.unwrap()')) {
-        return risks;
+function detectRule(rule, filePath, content) {
+    if (!isActive(rule, filePath, content)) {
+        return [];
     }
-    const lines = splitLines(content);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (line.includes('.unwrap()')) {
-            risks.push({
+    const lines = content.split('\n');
+    return lines.flatMap((line, index) => {
+        if (!matches(rule.finding, line) || isGuarded(rule, lines, index, content)) {
+            return [];
+        }
+        return [
+            {
                 file: filePath,
-                line: i + 1,
-                pattern: 'ACTIX_UNWRAP_IN_HANDLER',
-                severity: 'CRITICAL',
-                description: 'unwrap() in Actix-web request handler panics and crashes the worker thread on error.',
-                suggestedFix: 'Return a proper error response: use ? operator with impl ResponseError, or map_err() to return HttpResponse::InternalServerError().',
+                line: index + 1,
+                pattern: rule.pattern,
+                severity: rule.severity,
+                description: rule.description,
+                suggestedFix: rule.suggestedFix,
                 autoFixable: false,
-            });
-        }
-    }
-    return risks;
+            },
+        ];
+    });
 }
 export const frameworkDetector = {
     language: 'multi',
-    frameworks: ['Next.js', 'Express', 'Prisma', 'Django', 'Gin', 'Actix'],
-    fileExtensions: ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs'],
+    frameworks: rules.map((rule) => rule.framework),
+    fileExtensions: [...new Set(rules.flatMap((rule) => rule.fileExtensions))],
     detect(filePath, content) {
-        return [
-            ...detectNextJs(filePath, content),
-            ...detectExpress(filePath, content),
-            ...detectPrisma(filePath, content),
-            ...detectDjango(filePath, content),
-            ...detectGin(filePath, content),
-            ...detectActix(filePath, content),
-        ];
+        return rules.flatMap((rule) => detectRule(rule, filePath, content));
     },
 };
 //# sourceMappingURL=framework-detector.js.map

package/dist/engine/crash-shield/detectors/typescript-detector.js

@@ -1,3 +1,4 @@
+import { technologyValue } from '../../technology-registry.js';
 // P1: JSON.parse without Partial — CRITICAL
 const JSON_PARSE_CAST = /JSON\.parse\([^)]+\)\s+as\s+(?!Partial<|unknown|Record<string)[A-Z]/;
 // P2: Incomplete optional chaining — HIGH
@@ -178,7 +179,7 @@ function detectP5(filePath, content) {
     return risks;
 }
 export const typescriptDetector = {
-    language: 'TypeScript',
+    language: technologyValue('technology-typescript-ed0504'),
     fileExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
     detect(filePath, content) {
         if (isFileSuppressed(content)) {

package/dist/engine/criterion-identity.d.ts

@@ -1,5 +1,6 @@
 import type { CriterionIdentity, CriterionIdentityOptions } from '../types/criterion-identity.js';
 export type { CriterionIdentity, CriterionIdentityOptions } from '../types/criterion-identity.js';
+export declare function hasExplicitCriterionId(value: string): boolean;
 export declare function normalizeCriterionText(value: string): string;
 export declare function createCriterionIdentity(value: string, options?: CriterionIdentityOptions): CriterionIdentity;
 export declare function criterionIdentitiesMatch(left: CriterionIdentity, right: CriterionIdentity): boolean;

package/dist/engine/criterion-identity.js

@@ -1,5 +1,12 @@
 import { createHash } from 'node:crypto';
 const CRITERION_ID_PREFIX = /^(AC|AB)\s*-?\s*(\d+)\b\s*[:.)-]?\s*/i;
+export function hasExplicitCriterionId(value) {
+    const stripped = value
+        .normalize('NFKC')
+        .replace(/^[-*+]\s*\[[ xX]\]\s*/, '')
+        .trim();
+    return CRITERION_ID_PREFIX.test(stripped);
+}
 export function normalizeCriterionText(value) {
     return value
         .normalize('NFKC')

package/dist/engine/dashboard/data-loader.js

@@ -2,10 +2,11 @@
 // for the dashboard. All I/O is synchronous-style via fs promises.
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
 import { computeDashboardMetrics, computeHealthScore } from './kanban-logic.js';
 import { extractSectionBody } from '../spec-format/read-technical-section.js';
 /** Root data directory for all project data */
-const DATA_DIR = join(process.cwd(), 'data');
+const DATA_DIR = resolveStorageLayout().data;
 /** Safely read and parse a JSON file; returns null on any error */
 async function readJsonFile(filePath) {
     try {
@@ -323,18 +324,13 @@ export async function loadUsageStats() {
     const raw = await readJsonFile(usageFile);
     if (!raw) {
         return {
-            tier: 'unknown',
             callsToday: 0,
-            dailyLimit: null,
-            trialDaysLeft: null,
             isAvailable: false,
         };
     }
+    const today = new Date().toISOString().slice(0, 10);
     return {
-        tier: raw.tier ?? 'free',
-        callsToday: raw.callsToday ?? 0,
-        dailyLimit: raw.dailyLimit ?? null,
-        trialDaysLeft: raw.trialDaysLeft ?? null,
+        callsToday: (raw.events ?? []).filter((event) => event.timestamp?.startsWith(today)).length,
         isAvailable: true,
     };
 }

package/dist/engine/dashboard/templates-layout.js

@@ -194,9 +194,6 @@ function getPageStyles() {
   .usage-panel { background: var(--surface); border: 1px solid var(--border);
                  border-radius: var(--radius); padding: 1rem; margin-top: 1.5rem; }
   .usage-panel h3 { font-size: 0.9rem; font-weight: 600; margin-bottom: 0.75rem; color: var(--text-muted); }
-  .usage-tier { font-size: 1.1rem; font-weight: 700; color: var(--accent); }
-  .trial-warning { color: #f59e0b; font-size: 0.82rem; margin-top: 0.35rem; }
-  .trial-critical { color: #ef4444; font-weight: 600; }
   .status-indicator.updating { color: #f59e0b; }
   .shortcuts-overlay { display: none; position: fixed; inset: 0; background: rgba(0,0,0,0.7);
     z-index: 1000; align-items: center; justify-content: center; }

package/dist/engine/dashboard/templates-project.js

@@ -30,21 +30,9 @@ function renderUsagePanel(usage) {
       <div style="color:var(--text-muted);font-size:0.85rem">Sin datos de uso disponibles</div>
     </div>`;
     }
-    const tierLabel = usage.tier.charAt(0).toUpperCase() + usage.tier.slice(1);
-    const limitLabel = usage.dailyLimit !== null ? String(usage.dailyLimit) : '∞';
-    const callsLabel = `${usage.callsToday} / ${limitLabel}`;
-    let trialHtml = '';
-    if (usage.trialDaysLeft !== null) {
-        const isCritical = usage.trialDaysLeft <= 3;
-        trialHtml = `<div class="trial-warning ${isCritical ? 'trial-critical' : ''}">
-      Trial: ${usage.trialDaysLeft} día${usage.trialDaysLeft !== 1 ? 's' : ''} restante${usage.trialDaysLeft !== 1 ? 's' : ''}
-    </div>`;
-    }
     return `<div class="usage-panel">
     <h3>Uso</h3>
-    <div class="usage-tier">${escapeHtml(tierLabel)}</div>
-    <div style="font-size:0.82rem;color:var(--text-muted);margin-top:0.35rem">Llamadas hoy: ${escapeHtml(callsLabel)}</div>
-    ${trialHtml}
+    <div style="font-size:0.82rem;color:var(--text-muted);margin-top:0.35rem">Llamadas hoy: ${String(usage.callsToday)}</div>
   </div>`;
 }
 /** Render the health metrics panel */

package/dist/engine/data-projects-gc/gc-runner.d.ts

@@ -1,4 +1,9 @@
 import type { GcRunOptions, GcRunResult } from '../../types/index.js';
+/** Permanently remove catalog-owned trash entries whose TTL has elapsed. */
+export declare function purgeExpiredGcTrash(trashDir: string, nowMs?: number): Promise<{
+    purged: string[];
+    errors: string[];
+}>;
 /**
  * Run the GC pipeline:
  * 1. Scan data/projects/ for test-named, inactive, and orphaned directories.
@@ -8,4 +13,6 @@ import type { GcRunOptions, GcRunResult } from '../../types/index.js';
  * @param options - Run configuration (dataProjectsDir, apply, inactiveDays, …)
  */
 export declare function runGC(options: GcRunOptions): Promise<GcRunResult>;
+/** Restore one catalog-owned GC entry while its TTL metadata is present. */
+export declare function restoreGcTrash(trashEntryPath: string, dataProjectsDir: string): Promise<string>;
 //# sourceMappingURL=gc-runner.d.ts.map

package/dist/engine/data-projects-gc/gc-runner.js

@@ -1,7 +1,59 @@
 // engine/data-projects-gc/gc-runner.ts — SPEC-581
 // Orchestrates scan + optional deletion of data/projects/ garbage.
-import { rm } from 'node:fs/promises';
+import { access, mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { scanProjectDirs } from './scanner.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+const DEFAULT_TRASH_TTL_DAYS = 30;
+async function pathExists(path) {
+    return access(path).then(() => true, () => false);
+}
+function parseTrashMetadata(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('[Planu] Invalid GC trash metadata');
+    }
+    const parsed = value;
+    if (parsed.schemaVersion !== 1 ||
+        typeof parsed.originalPath !== 'string' ||
+        typeof parsed.trashedPath !== 'string' ||
+        typeof parsed.trashedAt !== 'string' ||
+        typeof parsed.expiresAt !== 'string' ||
+        !['test-named', 'inactive', 'orphaned'].includes(String(parsed.reason)) ||
+        Number.isNaN(Date.parse(parsed.trashedAt)) ||
+        Number.isNaN(Date.parse(parsed.expiresAt))) {
+        throw new Error('[Planu] Invalid GC trash metadata');
+    }
+    return parsed;
+}
+/** Permanently remove catalog-owned trash entries whose TTL has elapsed. */
+export async function purgeExpiredGcTrash(trashDir, nowMs = Date.now()) {
+    if (!isAbsolute(trashDir) || !Number.isFinite(nowMs)) {
+        throw new Error('[Planu] GC purge requires an absolute trash path and valid time');
+    }
+    const root = resolve(trashDir);
+    const metadataFiles = (await readdir(root).catch(() => [])).filter((name) => name.endsWith('.trash.json'));
+    const purged = [];
+    const errors = [];
+    for (const name of metadataFiles) {
+        const metadataPath = join(root, name);
+        try {
+            const metadata = parseTrashMetadata(JSON.parse(await readFile(metadataPath, 'utf8')));
+            const trashedPath = resolve(metadata.trashedPath);
+            if (dirname(trashedPath) !== root ||
+                `${trashedPath}.trash.json` !== metadataPath ||
+                Date.parse(metadata.expiresAt) > nowMs) {
+                continue;
+            }
+            await rm(trashedPath, { recursive: true, force: true });
+            await rm(metadataPath, { force: true });
+            purged.push(trashedPath);
+        }
+        catch (error) {
+            errors.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { purged, errors };
+}
 /**
  * Run the GC pipeline:
  * 1. Scan data/projects/ for test-named, inactive, and orphaned directories.
@@ -10,8 +62,12 @@ import { scanProjectDirs } from './scanner.js';
  *
  * @param options - Run configuration (dataProjectsDir, apply, inactiveDays, …)
  */
+// eslint-disable-next-line max-lines-per-function -- scan, recoverable move and TTL metadata form one atomic GC pipeline
 export async function runGC(options) {
-    const { dataProjectsDir, apply = false, inactiveDays = 90, registeredHashes, includeOrphans = false, } = options;
+    const { dataProjectsDir, apply = false, inactiveDays = 90, registeredHashes, includeOrphans = false, trashDir, trashTtlDays = DEFAULT_TRASH_TTL_DAYS, } = options;
+    if (!Number.isSafeInteger(trashTtlDays) || trashTtlDays < 1 || trashTtlDays > 3650) {
+        throw new Error('[Planu] trashTtlDays must be an integer between 1 and 3650');
+    }
     const scanResult = await scanProjectDirs(dataProjectsDir, {
         inactiveDays,
         registeredHashes,
@@ -24,11 +80,40 @@ export async function runGC(options) {
     ];
     const deleted = [];
     const errors = [];
+    const trashed = [];
+    const purgedExpired = [];
     if (apply) {
+        if (!trashDir) {
+            throw new Error('[Planu] trashDir is required when applying GC');
+        }
+        await mkdir(trashDir, { recursive: true, mode: 0o700 });
+        const purge = await purgeExpiredGcTrash(trashDir);
+        purgedExpired.push(...purge.purged);
+        errors.push(...purge.errors);
         for (const entry of candidates) {
             try {
-                await rm(entry.fullPath, { recursive: true, force: true });
+                const destination = join(trashDir, `${Date.now().toString()}-${entry.reason}-${entry.name}`);
+                await rename(entry.fullPath, destination);
+                const trashedAt = new Date();
+                const metadata = {
+                    schemaVersion: 1,
+                    originalPath: entry.fullPath,
+                    trashedPath: destination,
+                    trashedAt: trashedAt.toISOString(),
+                    expiresAt: new Date(trashedAt.getTime() + trashTtlDays * 24 * 60 * 60 * 1000).toISOString(),
+                    reason: entry.reason,
+                };
+                try {
+                    await atomicWriteFile(`${destination}.trash.json`, `${JSON.stringify(metadata, null, 2)}\n`, {
+                        mode: 0o600,
+                    });
+                }
+                catch (error) {
+                    await rename(destination, entry.fullPath);
+                    throw error;
+                }
                 deleted.push(entry.name);
+                trashed.push(destination);
             }
             catch (err) {
                 /* v8 ignore next 4 -- deletion error: typically OS-level permission or race condition */
@@ -44,8 +129,33 @@ export async function runGC(options) {
         orphaned: scanResult.orphaned,
         candidateCount: candidates.length,
         deleted,
+        trashed,
+        purgedExpired,
         errors,
         inactiveDays,
     };
 }
+/** Restore one catalog-owned GC entry while its TTL metadata is present. */
+export async function restoreGcTrash(trashEntryPath, dataProjectsDir) {
+    if (!isAbsolute(trashEntryPath) || !isAbsolute(dataProjectsDir)) {
+        throw new Error('[Planu] GC restore paths must be absolute');
+    }
+    const source = resolve(trashEntryPath);
+    const metadataPath = `${source}.trash.json`;
+    const parsed = parseTrashMetadata(JSON.parse(await readFile(metadataPath, 'utf8')));
+    const destination = resolve(parsed.originalPath);
+    if (resolve(parsed.trashedPath) !== source ||
+        dirname(destination) !== resolve(dataProjectsDir) ||
+        basename(destination) !== basename(parsed.originalPath) ||
+        Date.parse(parsed.expiresAt) <= Date.now()) {
+        throw new Error('[Planu] Invalid or expired GC trash metadata');
+    }
+    if (await pathExists(destination)) {
+        throw new Error(`[Planu] Cannot restore over existing project data: ${destination}`);
+    }
+    await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+    await rename(source, destination);
+    await rm(metadataPath, { force: true });
+    return destination;
+}
 //# sourceMappingURL=gc-runner.js.map

package/dist/engine/data-projects-gc/scanner.js

@@ -21,10 +21,14 @@ async function newestMtime(dirPath) {
         const dir = await opendir(dirPath);
         for await (const entry of dir) {
             try {
-                const s = await stat(join(dirPath, entry.name));
+                const entryPath = join(dirPath, entry.name);
+                const s = await stat(entryPath);
                 if (s.mtimeMs > newest) {
                     newest = s.mtimeMs;
                 }
+                if (entry.isDirectory()) {
+                    newest = Math.max(newest, await newestMtime(entryPath));
+                }
             }
             catch {
                 /* v8 ignore next 2 -- unreadable entry: OS-level permission error */