soloforge 1.0.0 → 1.1.0

package/dist/engine/scope_controller.d.ts

@@ -1,3 +1,16 @@
 import type { ScopeCheckResult } from "../types.js";
+/**
+ * 检查文件路径是否在允许的范围内，并可选地扫描文件内容中的敏感信息。
+ *
+ * 检查流程：
+ * 1. 解析符号链接并规范化路径
+ * 2. 遍历允许路径列表，执行目录边界校验（防止路径穿越攻击）
+ * 3. 若提供了内容参数，对内容进行密钥/敏感信息检测
+ *
+ * @param filePath - 待检查的文件路径
+ * @param allowedPaths - 允许的路径列表
+ * @param content - 可选的文件内容，用于敏感信息检测
+ * @returns 作用域检查结果，包含是否允许、原因、严重等级和密钥详情
+ */
 export declare function checkScope(filePath: string, allowedPaths: string[], content?: string): ScopeCheckResult;
 //# sourceMappingURL=scope_controller.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scope_controller.d.ts","sourceRoot":"","sources":["../../src/engine/scope_controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAqCpD,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,gBAAgB,CA4ClB"}
+{"version":3,"file":"scope_controller.d.ts","sourceRoot":"","sources":["../../src/engine/scope_controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA2EpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,gBAAgB,CA4ClB"}

package/dist/engine/scope_controller.js

@@ -1,38 +1,88 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+/**
+ * 作用域控制器 — 检查文件路径是否在允许范围内，并检测敏感信息泄露。
+ *
+ * 核心功能：
+ * 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 可用
+ */
 function isGitleaksAvailable() {
-    if (gitleaksAvailable === null) {
-        try {
-            execFileSync("which", ["gitleaks"], { stdio: "pipe" });
-            gitleaksAvailable = true;
-        }
-        catch {
-            gitleaksAvailable = false;
-        }
+    const now = Date.now();
+    if (gitleaksAvailable !== null && now - gitleaksCheckedAt < GITLEAKS_CACHE_TTL) {
+        return gitleaksAvailable;
+    }
+    try {
+        execFileSync("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 function checkScope(filePath, allowedPaths, content) {
-    // 解析符号链接并规范化
+    // 解析符号链接并规范化，防止通过符号链接绕过路径检查
     const resolvedPath = realPath(filePath);
-    // 检查路径是否在允许的 scope 内（防止路径穿越）
+    // 检查路径是否在允许的 scope 内（防止路径穿越攻击）
     const inScope = allowedPaths.some((allowed) => {
         const resolved = realPath(allowed);
         if (!resolvedPath.startsWith(resolved))
@@ -72,10 +122,18 @@ export function checkScope(filePath, allowedPaths, content) {
     }
     return { allowed: true, has_secrets: false, severity: "ok" };
 }
+/**
+ * 检测文件内容中的密钥和敏感信息。
+ * 优先使用 gitleaks 进行专业扫描；不可用时回退到正则匹配。
+ * @param content - 文件文本内容
+ * @param filePath - 文件路径（用于 gitleaks 的 `-s` 参数）
+ * @returns 检测到的敏感信息列表（最多返回 10 条 gitleaks 结果）
+ */
 function detectSecrets(content, filePath) {
-    // 如果可用，优先使用 gitleaks
+    // 如果可用，优先使用 gitleaks 进行更全面的扫描
     if (isGitleaksAvailable()) {
         try {
+            // --no-git: 不依赖 git 仓库；-f json: JSON 格式输出；-s: 指定扫描目标文件
             const result = execFileSync("gitleaks", ["detect", "--no-git", "-f", "json", "-s", filePath], { encoding: "utf-8", timeout: 5000 });
             const findings = JSON.parse(result || "[]");
             if (Array.isArray(findings) && findings.length > 0) {
@@ -99,7 +157,7 @@ function detectSecrets(content, filePath) {
         // 跳过使用环境变量的行
         if (SAFE_PATTERNS.some((p) => p.test(line)))
             continue;
-        // 跳过注释
+        // 跳过注释行（// 单行注释、# shebang/注释、<!-- HTML注释、* 多行注释片段）
         if (/^\s*(\/\/|#|<!--|\*)/.test(line))
             continue;
         for (const rule of SECRET_PATTERNS) {
@@ -110,6 +168,12 @@ function detectSecrets(content, filePath) {
     }
     return results;
 }
+/**
+ * 解析文件的真实路径（处理符号链接）。
+ * 若文件不存在或解析失败，回退到简单的路径规范化。
+ * @param p - 待解析的路径
+ * @returns 解析后的绝对路径
+ */
 function realPath(p) {
     try {
         return fs.realpathSync(path.resolve(p));

package/dist/engine/scope_controller.js.map

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

package/dist/engine/task_context.d.ts

@@ -1,34 +1,158 @@
 import type { TaskContext, ClassifyResult, ExpandResult, VerifyResult, FailureRecord, PlanResult, CodeReviewResult, DeliveryResult } from "../types.js";
+/**
+ * 任务上下文管理器 — 负责任务状态的创建、持久化、查询和生命周期管理。
+ * 状态文件存储在 stateDir 目录下，每个任务一个 JSON 文件。
+ * 使用 "current-task.json" 指针文件标记当前活跃任务。
+ */
 export declare class TaskContextManager {
     private stateDir;
     constructor(stateDir: string);
+    /** 获取状态存储目录路径 */
     getStateDir(): string;
+    /**
+     * 创建新任务上下文，生成唯一 ID 并持久化到磁盘。
+     * @param intent - 用户意图文本
+     * @param productProfile - 产品类型标识
+     * @returns 新创建的任务上下文
+     */
     create(intent: string, productProfile: string): Promise<TaskContext>;
+    /**
+     * 从磁盘加载任务上下文。
+     * @param taskId - 任务 ID
+     * @returns 任务上下文对象，不存在或解析失败时返回 null
+     */
     load(taskId: string): Promise<TaskContext | null>;
+    /**
+     * 持久化任务上下文到磁盘（先写临时文件再 rename，保证原子性）。
+     * @param ctx - 任务上下文对象
+     */
     save(ctx: TaskContext): Promise<void>;
+    /**
+     * 更新任务状态，严格校验状态转换合法性。
+     * @param taskId - 任务 ID
+     * @param status - 目标状态
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     * @throws 非法状态转换时抛出 Error
+     */
     updateStatus(taskId: string, status: TaskContext["status"]): Promise<TaskContext | null>;
+    /**
+     * 设置任务的分类结果。
+     * @param taskId - 任务 ID
+     * @param result - 分类结果
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setClassification(taskId: string, result: ClassifyResult): Promise<TaskContext | null>;
+    /**
+     * 设置任务的意图膨胀结果。
+     * @param taskId - 任务 ID
+     * @param result - 膨胀结果
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setExpansion(taskId: string, result: ExpandResult): Promise<TaskContext | null>;
+    /**
+     * 记录执行结果: 变更文件列表和可选的失败记录。
+     * 变更文件自动去重合并，失败记录追加到历史。
+     * @param taskId - 任务 ID
+     * @param changedFiles - 变更文件路径列表
+     * @param failure - 可选的失败记录
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setExecution(taskId: string, changedFiles: string[], failure?: FailureRecord): Promise<TaskContext | null>;
+    /**
+     * 设置任务的验证结果。
+     * @param taskId - 任务 ID
+     * @param result - 验证结果
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setVerification(taskId: string, result: VerifyResult): Promise<TaskContext | null>;
+    /**
+     * 获取当前活跃任务（通过 current-task.json 指针定位）。
+     * @returns 当前任务上下文，无活跃任务或读取失败时返回 null
+     */
     getCurrentTask(): Promise<TaskContext | null>;
+    /**
+     * 取消未完成的任务，将状态设为 failed。
+     * @param taskId - 任务 ID
+     * @returns 是否取消成功（已完成的任务无法取消）
+     */
     cancel(taskId: string): Promise<boolean>;
+    /**
+     * 判断任务是否可恢复（非 done / failed / classifying 状态均可恢复）。
+     * @param ctx - 任务上下文
+     * @returns 是否可恢复
+     */
     isResumable(ctx: TaskContext): boolean;
+    /**
+     * 根据当前状态生成恢复提示信息。
+     * @param ctx - 任务上下文
+     * @returns 恢复提示文本
+     */
     getResumeHint(ctx: TaskContext): string;
+    /**
+     * 列出最近的任务（按创建时间降序排列）。
+     * @param limit - 返回数量上限，默认 10
+     * @returns 任务摘要列表
+     */
     listRecent(limit?: number): Promise<Array<{
         task_id: string;
         intent: string;
         status: string;
         created_at: string;
     }>>;
+    /**
+     * 清理过期和超量任务: 删除超过 30 天的任务，超过 100 个时淘汰最旧的已完成/已失败任务。
+     * @returns 删除的任务数量
+     */
     cleanup(): Promise<number>;
+    /**
+     * 设置任务计划结果。
+     * @param taskId - 任务 ID
+     * @param result - 计划结果
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setPlanning(taskId: string, result: PlanResult): Promise<TaskContext | null>;
+    /**
+     * 设置代码审查结果，并基于审查发现计算阶段指令（能力 6）。
+     * @param taskId - 任务 ID
+     * @param result - 代码审查结果
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setCodeReview(taskId: string, result: CodeReviewResult): Promise<TaskContext | null>;
+    /**
+     * 设置交付结果。
+     * @param taskId - 任务 ID
+     * @param result - 交付结果
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     setDelivery(taskId: string, result: DeliveryResult): Promise<TaskContext | null>;
+    /**
+     * 更新修复循环状态（能力 3）: 递增尝试次数，记录失败阶段和自动修复能力。
+     * 同时统计同一阶段的复发次数。
+     * @param taskId - 任务 ID
+     * @param failurePhase - 发生失败的阶段名称
+     * @param autoRepairable - 是否可自动修复
+     * @param escalationReason - 可选的升级原因
+     * @returns 更新后的任务上下文，任务不存在或无执行记录时返回 null
+     */
     updateRepairLoop(taskId: string, failurePhase: string, autoRepairable: boolean, escalationReason?: string): Promise<TaskContext | null>;
+    /**
+     * 记录返工事件（能力 6）: 追踪从哪个阶段回退到哪个阶段及原因。
+     * 超过 MAX_REWORK 阈值时自动设置阶段指令为 stop_escalate。
+     * @param taskId - 任务 ID
+     * @param fromPhase - 源阶段
+     * @param toPhase - 目标阶段
+     * @param reason - 返工原因
+     * @returns 更新后的任务上下文，任务不存在时返回 null
+     */
     recordRework(taskId: string, fromPhase: string, toPhase: string, reason: string): Promise<TaskContext | null>;
+    /** 生成任务状态文件的完整路径 */
     private taskFilePath;
+    /** 当前任务指针文件路径 */
     private get pointerPath();
+    /**
+     * 写入当前任务指针文件。
+     * @param taskId - 任务 ID
+     */
     private writeCurrentPointer;
 }
 //# sourceMappingURL=task_context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"task_context.d.ts","sourceRoot":"","sources":["../../src/engine/task_context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAkD,cAAc,EAAE,MAAM,aAAa,CAAC;AAkBxM,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAK5B,WAAW,IAAI,MAAM;IAIf,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAcpE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAUjD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAaxF,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQtF,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQ/E,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA0BxB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQlF,cAAc,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAU7C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU9C,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO;IAItC,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM;IAYjC,UAAU,CAAC,KAAK,SAAK,GAAG,OAAO,CACnC,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAC/E;IAwBK,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAiD1B,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQ5E,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAYpF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAUhF,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA+BvI,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA2BnH,OAAO,CAAC,YAAY;IAIpB,OAAO,KAAK,WAAW,GAEtB;YAEa,mBAAmB;CAGlC"}
+{"version":3,"file":"task_context.d.ts","sourceRoot":"","sources":["../../src/engine/task_context.ts"],"names":[],"mappings":"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"}