soloforge 1.1.2 → 1.1.31

package/dist/engine/pipeline/scope_controller.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execa } from "execa";
+import { debugLog } from "../core/logger.js";
+import { safeJsonParse } from "../core/helpers.js";
+import { hasGlobPattern, isPathInScope } from "../core/path_scope_utils.js";
+/**
+ * 作用域控制器 — 检查文件路径是否在允许范围内，并检测敏感信息泄露。
+ *
+ * 核心功能：
+ * 1. 路径范围校验：解析符号链接后，判断文件是否在声明的允许路径内（防止路径穿越）
+ * 2. 敏感信息检测：优先使用 gitleaks 扫描密钥，回退到正则表达式匹配
+ * 3. 安全模式识别：跳过通过环境变量引用的配置行（如 process.env.X）
+ */
+/** gitleaks 可用性缓存，避免重复执行 which 检测 */
+let gitleaksAvailable = null;
+let gitleaksCheckedAt = 0;
+const GITLEAKS_CACHE_TTL = 5 * 60 * 1000; // 5 分钟
+/**
+ * 检测系统中是否安装了 gitleaks 密钥扫描工具。
+ * 结果会被缓存 5 分钟，超时后重新检测。
+ * @returns true 表示 gitleaks 可用
+ */
+async function isGitleaksAvailable() {
+    const now = Date.now();
+    if (gitleaksAvailable !== null && now - gitleaksCheckedAt < GITLEAKS_CACHE_TTL) {
+        return gitleaksAvailable;
+    }
+    try {
+        await execa("which", ["gitleaks"], { stdio: "pipe" });
+        gitleaksAvailable = true;
+    }
+    catch {
+        gitleaksAvailable = false;
+    }
+    gitleaksCheckedAt = now;
+    return gitleaksAvailable;
+}
+/**
+ * 密钥/敏感信息正则匹配规则。
+ * 每条规则包含：匹配正则、类型标识、严重等级（blocked 表示禁止，warning 表示警告）。
+ *
+ * 覆盖的密钥类型：AWS 访问密钥、API 密钥、数据库密码、JWT 密钥等。
+ */
+const SECRET_PATTERNS = [
+    // AWS 访问密钥 ID：以 AKIA 开头的 20 位大写字母数字
+    { pattern: /AKIA[0-9A-Z]{16}/, type: "aws_access_key", severity: "blocked" },
+    // AWS 密钥赋值语句
+    { pattern: /aws_secret_access_key\s*=\s*['"][^'"]+['"]/, type: "aws_secret", severity: "blocked" },
+    // 通用 API 密钥（如 OpenAI sk- 前缀）
+    { pattern: /sk-[a-zA-Z0-9]{32,}/, type: "api_key", severity: "blocked" },
+    // 32 位以上十六进制字符串（可能是令牌或哈希值）
+    { pattern: /['"][a-f0-9]{32,}['"]/, type: "possible_token", severity: "warning" },
+    // 数据库密码赋值语句（8 位以上）
+    { pattern: /password\s*=\s*['"][^'"]{8,}['"]/, type: "db_password", severity: "blocked" },
+    // JWT 签名密钥
+    { pattern: /jwt_secret\s*=\s*['"][^'"]+['"]/, type: "jwt_secret", severity: "blocked" },
+    // 通用密钥赋值
+    { pattern: /secret_key\s*=\s*['"][^'"]+['"]/, type: "secret_key", severity: "blocked" },
+];
+/**
+ * 安全模式正则列表 — 匹配到这些模式的行将被跳过，
+ * 因为它们通过环境变量引用敏感值，而非硬编码。
+ */
+const SAFE_PATTERNS = [
+    /process\.env\./,
+    /System\.getenv\(/,
+    /import\.meta\.env\./,
+    // 环境变量名本身不是敏感值
+    /NODE_ENV/,
+];
+/**
+ * 检查文件路径是否在允许的范围内，并可选地扫描文件内容中的敏感信息。
+ *
+ * 检查流程：
+ * 1. 解析符号链接并规范化路径
+ * 2. 遍历允许路径列表，执行目录边界校验（防止路径穿越攻击）
+ * 3. 若提供了内容参数，对内容进行密钥/敏感信息检测
+ *
+ * @param filePath - 待检查的文件路径
+ * @param allowedPaths - 允许的路径列表
+ * @param content - 可选的文件内容，用于敏感信息检测
+ * @returns 作用域检查结果，包含是否允许、原因、严重等级和密钥详情
+ */
+export async function checkScope(filePath, allowedPaths, content) {
+    // 输入校验：null/undefined 安全拒绝而非崩溃
+    if (!filePath || typeof filePath !== "string") {
+        return { allowed: false, reason: "文件路径无效", has_secrets: false, severity: "blocked" };
+    }
+    if (!Array.isArray(allowedPaths) || allowedPaths.length === 0) {
+        return { allowed: false, reason: "无允许路径", has_secrets: false, severity: "blocked" };
+    }
+    debugLog(`作用域检查: 检查文件 ${filePath}`);
+    // 解析符号链接并规范化，防止通过符号链接绕过路径检查
+    const resolvedPath = realPath(filePath);
+    // 检查路径是否在允许的 scope 内（防止路径穿越攻击）
+    const inScope = allowedPaths.some((allowed) => {
+        const resolved = hasGlobPattern(allowed)
+            ? (path.isAbsolute(allowed) ? allowed : path.resolve(allowed))
+            : realPath(allowed);
+        return isPathInScope(resolvedPath, resolved);
+    });
+    if (!inScope) {
+        debugLog(`作用域检查: 文件 ${filePath} 不在允许的 scope 内`);
+        return {
+            allowed: false,
+            reason: `文件 ${filePath} 不在允许的 scope 内`,
+            has_secrets: false,
+            severity: "blocked",
+        };
+    }
+    // 如果提供了内容，检查密钥
+    if (content) {
+        const secretResult = await detectSecrets(content, filePath);
+        if (secretResult.length > 0) {
+            const hasBlocked = secretResult.some((s) => s.severity === "blocked");
+            debugLog(`作用域检查: 文件 ${filePath} 检测到敏感信息: ${secretResult.map((s) => s.type).join(", ")}`);
+            return {
+                allowed: !hasBlocked,
+                reason: hasBlocked
+                    ? `检测到密钥/密码: ${secretResult.map((s) => s.type).join(", ")}。请使用环境变量。`
+                    : `可能包含敏感信息: ${secretResult.map((s) => s.type).join(", ")}`,
+                has_secrets: true,
+                secret_details: secretResult.map((s) => ({
+                    file: filePath,
+                    line: s.line,
+                    type: s.type,
+                })),
+                severity: hasBlocked ? "blocked" : "warning",
+            };
+        }
+    }
+    return { allowed: true, has_secrets: false, severity: "ok" };
+}
+/**
+ * 检测文件内容中的密钥和敏感信息。
+ * 优先使用 gitleaks 进行专业扫描；不可用时回退到正则匹配。
+ * @param content - 文件文本内容
+ * @param filePath - 文件路径（用于 gitleaks 的 `-s` 参数）
+ * @returns 检测到的敏感信息列表（最多返回 10 条 gitleaks 结果）
+ */
+async function detectSecrets(content, filePath) {
+    // 如果可用，优先使用 gitleaks 进行更全面的扫描
+    if (await isGitleaksAvailable()) {
+        try {
+            // --no-git: 不依赖 git 仓库；-f json: JSON 格式输出；-s: 指定扫描目标文件
+            const { stdout: result } = await execa("gitleaks", ["detect", "--no-git", "-f", "json", "-s", "--", filePath], // -- 防止 filePath 被解析为 flag
+            { timeout: 5000 });
+            const findings = safeJsonParse(result || "[]");
+            if (Array.isArray(findings) && findings.length > 0) {
+                return findings.slice(0, 10).map((f) => ({
+                    type: String(f.RuleID || "gitleaks_finding"),
+                    line: Number(f.StartLine || 0),
+                    severity: "blocked",
+                }));
+            }
+            return []; // gitleaks 未发现问题
+        }
+        catch (e) {
+            // gitleaks exit 1 = 检测到问题，stdout 包含 JSON
+            const stdout = e instanceof Error ? e.stdout : undefined;
+            if (stdout) {
+                try {
+                    const findings = safeJsonParse(stdout);
+                    if (Array.isArray(findings) && findings.length > 0) {
+                        return findings.slice(0, 10).map((f) => ({
+                            type: String(f.RuleID || "gitleaks_finding"),
+                            line: Number(f.StartLine || 0),
+                            severity: "blocked",
+                        }));
+                    }
+                }
+                catch { /* JSON parse failed, fall through to regex */ }
+            }
+            // 真正的错误（非 exit 1），回退到正则匹配
+        }
+    }
+    // 回退: 基于正则的检测
+    const lines = content.split("\n");
+    const results = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // 跳过使用环境变量的行
+        if (SAFE_PATTERNS.some((p) => p.test(line)))
+            continue;
+        // 跳过注释行（// 单行注释、# shebang/注释、<!-- HTML注释、* 多行注释片段）
+        if (/^\s*(\/\/|#|<!--|\*)/.test(line))
+            continue;
+        for (const rule of SECRET_PATTERNS) {
+            if (rule.pattern.test(line)) {
+                results.push({ type: rule.type, line: i + 1, severity: rule.severity });
+            }
+        }
+    }
+    return results;
+}
+/**
+ * 解析文件的真实路径（处理符号链接）。
+ * 若文件不存在或解析失败，回退到简单的路径规范化。
+ * @param p - 待解析的路径
+ * @returns 解析后的绝对路径
+ */
+function realPath(p) {
+    try {
+        return fs.realpathSync(path.resolve(p));
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+//# sourceMappingURL=scope_controller.js.map

package/dist/engine/pipeline/scope_controller.js.map

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

package/dist/engine/pipeline/scope_lease.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Scope Lease — 追踪任务对文件的 advisory 租约。
+ *
+ * CAP-011 实验性: advisory only, 不 hard block, 不阻止写入。
+ * 职责: 记录哪个任务正在操作哪些文件，供其他任务查询冲突。
+ *
+ * 生命周期:
+ * - 任务进入 executing 时 acquire
+ * - 任务完成/失败/取消时 release
+ * - 其他任务写前可 queryLease 查询 advisory 冲突
+ */
+/** 租约条目 */
+export interface LeaseEntry {
+    task_id: string;
+    file_paths: string[];
+    acquired_at: string;
+    released_at: string | null;
+}
+/** 租约冲突信息 */
+export interface LeaseConflict {
+    file_path: string;
+    leased_by: string;
+    lease_acquired_at: string;
+    severity: "advisory";
+    message: string;
+}
+/** 租约摘要 */
+export interface LeaseSummary {
+    active_leases: number;
+    total_files_leased: number;
+    leased_by_task: Record<string, string[]>;
+}
+/** 范围租约存储 */
+export declare class ScopeLeaseStore {
+    private filePath;
+    private leases;
+    private loaded;
+    /**
+     * 创建范围租约存储实例。
+     * @param stateDir - 状态存储目录路径
+     */
+    constructor(stateDir: string);
+    /** 从磁盘加载租约数据（首次访问时自动调用） */
+    private ensureLoaded;
+    /** 将租约数据持久化到磁盘 */
+    private persist;
+    /**
+     * 为任务获取文件范围租约。
+     * @param taskId - 任务 ID
+     * @param filePaths - 任务操作的文件路径列表
+     * @returns 创建的租约条目
+     */
+    acquire(taskId: string, filePaths: string[]): LeaseEntry;
+    /**
+     * 释放任务的文件范围租约。
+     * 释放前检查是否有其他活跃任务持有重叠路径。
+     * @param taskId - 任务 ID
+     * @returns 释放结果，包含是否成功和冲突警告
+     */
+    release(taskId: string): {
+        released: boolean;
+        warnings: string[];
+    };
+    /**
+     * 查询指定文件是否存在与其他任务的租约冲突。
+     * @param taskId - 当前任务 ID（排除自身）
+     * @param filePath - 要查询的文件路径
+     * @returns 租约冲突信息，无冲突时返回 null
+     */
+    queryLease(taskId: string, filePath: string): LeaseConflict | null;
+    /**
+     * 获取所有活跃的租约列表。
+     * @returns 活跃租约条目数组
+     */
+    getActiveLeases(): LeaseEntry[];
+    /**
+     * 获取指定任务的租约信息。
+     * @param taskId - 任务 ID
+     * @returns 对应的租约条目，未找到时返回 null
+     */
+    getLeaseForTask(taskId: string): LeaseEntry | null;
+    /**
+     * 获取租约摘要统计。
+     * @returns 租约摘要信息
+     */
+    getSummary(): LeaseSummary;
+    /**
+     * 清除所有租约数据。
+     */
+    clear(): void;
+}
+//# sourceMappingURL=scope_lease.d.ts.map

package/dist/engine/pipeline/scope_lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope_lease.d.ts","sourceRoot":"","sources":["../../../src/engine/pipeline/scope_lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,WAAW;AACX,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,aAAa;AACb,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,WAAW;AACX,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC1C;AAED,aAAa;AACb,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,MAAM,CAAS;IAEvB;;;OAGG;gBACS,QAAQ,EAAE,MAAM;IAO5B,2BAA2B;IAC3B,OAAO,CAAC,YAAY;IAgBpB,kBAAkB;IAClB,OAAO,CAAC,OAAO;IAOf;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU;IAexD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE;IA0BlE;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAoBlE;;;OAGG;IACH,eAAe,IAAI,UAAU,EAAE;IAK/B;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAKlD;;;OAGG;IACH,UAAU,IAAI,YAAY;IAe1B;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd"}

package/dist/engine/pipeline/scope_lease.js

@@ -0,0 +1,180 @@
+/**
+ * Scope Lease — 追踪任务对文件的 advisory 租约。
+ *
+ * CAP-011 实验性: advisory only, 不 hard block, 不阻止写入。
+ * 职责: 记录哪个任务正在操作哪些文件，供其他任务查询冲突。
+ *
+ * 生命周期:
+ * - 任务进入 executing 时 acquire
+ * - 任务完成/失败/取消时 release
+ * - 其他任务写前可 queryLease 查询 advisory 冲突
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { debug } from "../core/logger.js";
+import { safeJsonParse } from "../core/helpers.js";
+import { isPathInScope } from "../core/path_scope_utils.js";
+/** 范围租约存储 */
+export class ScopeLeaseStore {
+    filePath;
+    leases = new Map();
+    loaded = false;
+    /**
+     * 创建范围租约存储实例。
+     * @param stateDir - 状态存储目录路径
+     */
+    constructor(stateDir) {
+        this.filePath = path.join(stateDir, "scope-leases.json");
+        if (!fs.existsSync(stateDir)) {
+            // 无操作
+        }
+    }
+    /** 从磁盘加载租约数据（首次访问时自动调用） */
+    ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const data = fs.readFileSync(this.filePath, "utf-8");
+            const entries = safeJsonParse(data) ?? [];
+            for (const e of entries) {
+                if (e.released_at === null) {
+                    this.leases.set(e.task_id, e);
+                }
+            }
+        }
+        catch {
+            this.leases = new Map();
+        }
+    }
+    /** 将租约数据持久化到磁盘 */
+    persist() {
+        const entries = [...this.leases.values()];
+        const tmpPath = `${this.filePath}.tmp`;
+        fs.writeFileSync(tmpPath, JSON.stringify(entries, null, 2));
+        fs.renameSync(tmpPath, this.filePath);
+    }
+    /**
+     * 为任务获取文件范围租约。
+     * @param taskId - 任务 ID
+     * @param filePaths - 任务操作的文件路径列表
+     * @returns 创建的租约条目
+     */
+    acquire(taskId, filePaths) {
+        debug("ScopeLease", "获取租约", taskId, "文件数:", filePaths.length);
+        this.ensureLoaded();
+        const resolved = filePaths.map(f => path.resolve(f));
+        const entry = {
+            task_id: taskId,
+            file_paths: resolved,
+            acquired_at: new Date().toISOString(),
+            released_at: null,
+        };
+        this.leases.set(taskId, entry);
+        this.persist();
+        return entry;
+    }
+    /**
+     * 释放任务的文件范围租约。
+     * 释放前检查是否有其他活跃任务持有重叠路径。
+     * @param taskId - 任务 ID
+     * @returns 释放结果，包含是否成功和冲突警告
+     */
+    release(taskId) {
+        debug("ScopeLease", "释放租约", taskId);
+        this.ensureLoaded();
+        const entry = this.leases.get(taskId);
+        if (!entry || entry.released_at) {
+            return { released: false, warnings: [] };
+        }
+        // 检查是否有其他活跃任务依赖相同文件路径
+        const warnings = [];
+        for (const [otherId, other] of this.leases) {
+            if (otherId === taskId || other.released_at)
+                continue;
+            const overlap = entry.file_paths.some(p => other.file_paths.some(op => op === p || op.startsWith(p + "/") || p.startsWith(op + "/")));
+            if (overlap) {
+                warnings.push(`任务 ${otherId} 的 scope 与本任务有重叠，释放后可能出现写入冲突`);
+            }
+        }
+        entry.released_at = new Date().toISOString();
+        this.leases.delete(taskId);
+        this.persist();
+        return { released: true, warnings };
+    }
+    /**
+     * 查询指定文件是否存在与其他任务的租约冲突。
+     * @param taskId - 当前任务 ID（排除自身）
+     * @param filePath - 要查询的文件路径
+     * @returns 租约冲突信息，无冲突时返回 null
+     */
+    queryLease(taskId, filePath) {
+        this.ensureLoaded();
+        const resolved = path.resolve(filePath);
+        for (const [ownerId, entry] of this.leases) {
+            if (ownerId === taskId)
+                continue;
+            for (const leased of entry.file_paths) {
+                if (leased === resolved || isParentPath(leased, resolved)) {
+                    return {
+                        file_path: resolved,
+                        leased_by: ownerId,
+                        lease_acquired_at: entry.acquired_at,
+                        severity: "advisory",
+                        message: `advisory: file is in scope of task ${ownerId} (leased since ${entry.acquired_at})`,
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * 获取所有活跃的租约列表。
+     * @returns 活跃租约条目数组
+     */
+    getActiveLeases() {
+        this.ensureLoaded();
+        return [...this.leases.values()];
+    }
+    /**
+     * 获取指定任务的租约信息。
+     * @param taskId - 任务 ID
+     * @returns 对应的租约条目，未找到时返回 null
+     */
+    getLeaseForTask(taskId) {
+        this.ensureLoaded();
+        return this.leases.get(taskId) ?? null;
+    }
+    /**
+     * 获取租约摘要统计。
+     * @returns 租约摘要信息
+     */
+    getSummary() {
+        this.ensureLoaded();
+        const leasedByTask = {};
+        let totalFiles = 0;
+        for (const [taskId, entry] of this.leases) {
+            leasedByTask[taskId] = [...entry.file_paths];
+            totalFiles += entry.file_paths.length;
+        }
+        return {
+            active_leases: this.leases.size,
+            total_files_leased: totalFiles,
+            leased_by_task: leasedByTask,
+        };
+    }
+    /**
+     * 清除所有租约数据。
+     */
+    clear() {
+        debug("ScopeLease", "清除所有租约");
+        this.leases.clear();
+        this.loaded = true;
+        this.persist();
+    }
+}
+/** 判断 child 路径是否在 parent 路径下 */
+function isParentPath(parent, child) {
+    return isPathInScope(child, parent, { caseSensitive: true });
+}
+//# sourceMappingURL=scope_lease.js.map

package/dist/engine/pipeline/scope_lease.js.map

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

package/dist/engine/pipeline/scope_resolver.d.ts

@@ -0,0 +1,11 @@
+import type { ClassifyResult, ProjectConfig, ScopeResult } from "../../types/index.js";
+import type { IntentRouteDecision } from "./intent_router.js";
+export interface ResolveTaskScopeInput {
+    projectPath: string;
+    config: ProjectConfig;
+    classification: ClassifyResult;
+    degraded: boolean;
+    routeDecision?: IntentRouteDecision;
+}
+export declare function resolveTaskScope(input: ResolveTaskScopeInput): ScopeResult;
+//# sourceMappingURL=scope_resolver.d.ts.map

package/dist/engine/pipeline/scope_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope_resolver.d.ts","sourceRoot":"","sources":["../../../src/engine/pipeline/scope_resolver.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAIb,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAW9D,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAigBD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,WAAW,CA6F1E"}