@openprd/cli 0.1.18 → 0.1.21

package/src/runtime/write-set.js

@@ -0,0 +1,206 @@
+/*
+ * ## 核心功能
+ * 规范化任务写入范围，并以安全优先的方式判断两个 write-set 是否可能相交。
+ *
+ * ## 输入
+ * 接收 include/exclude 路径或 glob；数组简写等价于 include，空范围按全项目处理。
+ *
+ * ## 输出
+ * 导出 normalizeWriteSet、writeSetsIntersect 与包含冲突路径的 explainWriteSetIntersection。
+ *
+ * ## 定位
+ * 位于 runtime 并发控制层；只计算路径集合，不读取文件系统或修改 claim。
+ *
+ * ## 依赖
+ * 仅使用 Node.js path 模块完成 POSIX 路径标准化。
+ *
+ * ## 维护规则
+ * 判定必须避免漏报写冲突；不能证明互斥的复杂 glob 应保守返回相交。
+ */
+
+import path from 'node:path';
+
+const BROAD_PATTERN = '**/*';
+const GLOB_TOKEN = /[*?[]/;
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function listFrom(value) {
+  if (value === null || value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export function normalizeWritePattern(value) {
+  const original = String(value ?? '').trim();
+  if (!original) return null;
+
+  const slashNormalized = original.replaceAll('\\', '/');
+  if (slashNormalized.includes('\0')) {
+    throw new TypeError('OpenPrd write-set patterns cannot contain null bytes.');
+  }
+  if (path.posix.isAbsolute(slashNormalized) || /^[A-Za-z]:\//.test(slashNormalized)) {
+    throw new TypeError(`OpenPrd write-set patterns must be project-relative: ${original}`);
+  }
+
+  const hadTrailingSlash = slashNormalized.endsWith('/');
+  let normalized = slashNormalized.replace(/^(?:\.\/)+/, '');
+  normalized = path.posix.normalize(normalized);
+  if (normalized === '.' || normalized === '') return BROAD_PATTERN;
+  if (normalized === '..' || normalized.startsWith('../')) {
+    throw new TypeError(`OpenPrd write-set patterns cannot escape the project root: ${original}`);
+  }
+  if (hadTrailingSlash) normalized = `${normalized.replace(/\/+$/, '')}/**`;
+  if (normalized === '**') return BROAD_PATTERN;
+  return normalized;
+}
+
+export function normalizeWriteSet(value = null) {
+  const source = Array.isArray(value) || typeof value === 'string'
+    ? { include: value }
+    : (value ?? {});
+  const includeSource = source.include ?? source.includes ?? source.paths;
+  const excludeSource = source.exclude ?? source.excludes;
+  const include = uniqueSorted(listFrom(includeSource).map(normalizeWritePattern).filter(Boolean));
+  const exclude = uniqueSorted(listFrom(excludeSource).map(normalizeWritePattern).filter(Boolean));
+  return {
+    include: include.length > 0 ? include : [BROAD_PATTERN],
+    exclude,
+  };
+}
+
+function hasGlob(pattern) {
+  return GLOB_TOKEN.test(pattern);
+}
+
+function globRegExp(pattern) {
+  let source = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    const next = pattern[index + 1];
+    if (character === '*' && next === '*') {
+      const after = pattern[index + 2];
+      if (after === '/') {
+        source += '(?:.*/)?';
+        index += 2;
+      } else {
+        source += '.*';
+        index += 1;
+      }
+      continue;
+    }
+    if (character === '*') {
+      source += '[^/]*';
+      continue;
+    }
+    if (character === '?') {
+      source += '[^/]';
+      continue;
+    }
+    if ('\\^$+?.()|{}[]'.includes(character)) source += `\\${character}`;
+    else source += character;
+  }
+  source += '$';
+  return new RegExp(source);
+}
+
+function patternMatches(pattern, candidate) {
+  return globRegExp(pattern).test(candidate);
+}
+
+function staticRoot(pattern) {
+  const wildcardIndex = pattern.search(GLOB_TOKEN);
+  const raw = wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
+  return raw.replace(/\/+$/, '');
+}
+
+function pathWithin(candidate, parent) {
+  if (!parent) return true;
+  return candidate === parent || candidate.startsWith(`${parent}/`);
+}
+
+function prefixGlobRoot(pattern) {
+  if (pattern === BROAD_PATTERN) return '';
+  if (pattern.endsWith('/**/*')) return pattern.slice(0, -5).replace(/\/+$/, '');
+  if (pattern.endsWith('/**')) return pattern.slice(0, -3).replace(/\/+$/, '');
+  return null;
+}
+
+function patternContainedBy(candidate, cover) {
+  if (candidate === cover || cover === BROAD_PATTERN) return true;
+  if (!hasGlob(candidate)) return patternMatches(cover, candidate);
+
+  const coverRoot = prefixGlobRoot(cover);
+  if (coverRoot !== null) {
+    const candidateRoot = staticRoot(candidate);
+    return pathWithin(candidateRoot, coverRoot);
+  }
+  return false;
+}
+
+function patternsMayIntersect(left, right) {
+  if (left === right || left === BROAD_PATTERN || right === BROAD_PATTERN) return true;
+  if (!hasGlob(left)) {
+    if (!right.includes('[')) return patternMatches(right, left);
+    return pathWithin(staticRoot(left), staticRoot(right)) || pathWithin(staticRoot(right), staticRoot(left));
+  }
+  if (!hasGlob(right)) {
+    if (!left.includes('[')) return patternMatches(left, right);
+    return pathWithin(staticRoot(left), staticRoot(right)) || pathWithin(staticRoot(right), staticRoot(left));
+  }
+
+  const leftRoot = staticRoot(left);
+  const rightRoot = staticRoot(right);
+  if (!leftRoot || !rightRoot) return true;
+  return pathWithin(leftRoot, rightRoot) || pathWithin(rightRoot, leftRoot);
+}
+
+function overlapPattern(left, right) {
+  if (patternContainedBy(left, right)) return left;
+  if (patternContainedBy(right, left)) return right;
+  if (!hasGlob(left) && patternMatches(right, left)) return left;
+  if (!hasGlob(right) && patternMatches(left, right)) return right;
+  return null;
+}
+
+function overlapIsExcluded(pattern, writeSet) {
+  if (!pattern) return false;
+  return writeSet.exclude.some((excluded) => patternContainedBy(pattern, excluded));
+}
+
+export function explainWriteSetIntersection(leftValue, rightValue) {
+  const left = normalizeWriteSet(leftValue);
+  const right = normalizeWriteSet(rightValue);
+  for (const leftPattern of left.include) {
+    for (const rightPattern of right.include) {
+      if (!patternsMayIntersect(leftPattern, rightPattern)) continue;
+      const overlap = overlapPattern(leftPattern, rightPattern);
+      if (overlapIsExcluded(overlap, left) || overlapIsExcluded(overlap, right)) continue;
+      return {
+        intersects: true,
+        left,
+        right,
+        leftPattern,
+        rightPattern,
+        overlapPattern: overlap,
+        conservative: overlap === null,
+      };
+    }
+  }
+  return {
+    intersects: false,
+    left,
+    right,
+    leftPattern: null,
+    rightPattern: null,
+    overlapPattern: null,
+    conservative: false,
+  };
+}
+
+export function writeSetsIntersect(left, right) {
+  return explainWriteSetIntersection(left, right).intersects;
+}
+
+export { BROAD_PATTERN };

package/src/session-binding.js

@@ -8,6 +8,16 @@ const OPENPRD_HARNESS_REQUIREMENT_GATE = path.join(OPENPRD_HARNESS_DIR, 'require
 const OPENPRD_HARNESS_SESSION_BINDINGS_DIR = path.join(OPENPRD_HARNESS_DIR, 'session-bindings');
 const OPENPRD_STATE_CURRENT = path.join('.openprd', 'state', 'current.json');
 
+let sessionBindingWriteEnabled = true;
+
+function setSessionBindingWriteEnabled(enabled) {
+  sessionBindingWriteEnabled = enabled;
+}
+
+function isSessionBindingWriteEnabled() {
+  return sessionBindingWriteEnabled;
+}
+
 function normalizeSessionId(sessionId) {
   const text = String(sessionId ?? '').trim();
   return text || null;
@@ -57,6 +67,9 @@ async function upsertSessionBinding(projectRoot, sessionId, patch = {}) {
   if (!normalized) {
     return null;
   }
+  if (!sessionBindingWriteEnabled) {
+    return { sessionId: normalized, path: null, skipped: true, reason: 'session-binding-write-disabled' };
+  }
   const filePath = sessionBindingPath(projectRoot, normalized);
   const previous = await readJson(filePath).catch(() => null);
   const next = {
@@ -84,9 +97,7 @@ async function upsertSessionBinding(projectRoot, sessionId, patch = {}) {
     gateStatus: patch.gateStatus ?? next.gateStatus ?? null,
     gateActive: patch.gateActive ?? next.gateActive ?? false,
     bindingPath: filePath,
-    statePath: normalized
-      ? path.join(projectRoot, '.openprd', 'harness', 'session-states', `${normalized.replace(/[^A-Za-z0-9._-]/g, '_')}.json`)
-      : null,
+    statePath: path.join(projectRoot, '.openprd', 'harness', 'session-states', `${normalized.replace(/[^A-Za-z0-9._-]/g, '_')}.json`),
     updatedAt: next.updatedAt,
   });
   return {
@@ -167,9 +178,11 @@ async function syncSessionBindingFromChange(projectRoot, changeId, options = {})
 }
 
 export {
+  isSessionBindingWriteEnabled,
   readLegacyRequirementGate,
   readSessionBinding,
   sessionBindingPath,
+  setSessionBindingWriteEnabled,
   syncSessionBindingFromChange,
   syncSessionBindingFromReview,
   syncSessionBindingFromSnapshot,

package/src/session-registry.js

@@ -1,11 +1,18 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { appendJsonl, cjoin, exists, readJsonl } from './fs-utils.js';
+import { atomicWriteText, withFileLock } from './kernel/atomic-store.js';
 import { timestamp } from './time.js';
 import { resolveOpenPrdHome } from './workspace-registry.js';
 
 const OPENPRD_SESSION_REGISTRY = cjoin('registry', 'sessions.jsonl');
 
+let registryWriteEnabled = true;
+
+function setRegistryWriteEnabled(enabled) {
+  registryWriteEnabled = enabled;
+}
+
 function normalizeSessionId(sessionId) {
   const text = String(sessionId ?? '').trim();
   return text || null;
@@ -84,6 +91,20 @@ async function readSessionRegistry(options = {}) {
         ...entry,
         reason: 'missing-openprd-marker',
       });
+      continue;
+    }
+    if (entry.bindingPath && !(await exists(entry.bindingPath))) {
+      staleEntries.push({
+        ...entry,
+        reason: 'missing-binding',
+      });
+      continue;
+    }
+    if (entry.statePath && !(await exists(entry.statePath))) {
+      staleEntries.push({
+        ...entry,
+        reason: 'missing-state',
+      });
     }
   }
   return {
@@ -109,6 +130,9 @@ async function upsertSessionRegistryEntry(projectRoot, sessionId, patch = {}, op
   if (!normalized) {
     return null;
   }
+  if (!registryWriteEnabled) {
+    return { home: null, registryPath: null, entry: { sessionId: normalized }, status: 'skipped', reason: 'registry-write-disabled' };
+  }
   const registry = await readSessionRegistry(options);
   const workspaceRoot = path.resolve(projectRoot);
   const realpath = await fs.realpath(workspaceRoot).catch(() => workspaceRoot);
@@ -140,7 +164,7 @@ async function upsertSessionRegistryEntry(projectRoot, sessionId, patch = {}, op
     lastUpdatedAt: patch.updatedAt ?? recordedAt,
     recordedAt,
   });
-  await appendJsonl(registry.registryPath, entry);
+  await withFileLock(`${registry.registryPath}.lock`, () => appendJsonl(registry.registryPath, entry));
   return {
     home: registry.home,
     registryPath: registry.registryPath,
@@ -150,10 +174,44 @@ async function upsertSessionRegistryEntry(projectRoot, sessionId, patch = {}, op
   };
 }
 
+function registryBackupName() {
+  return `sessions-${new Date().toISOString().replace(/[:.]/g, '-')}.jsonl`;
+}
+
+async function compactSessionRegistry(options = {}) {
+  const registryPath = sessionRegistryFilePath(options);
+  return withFileLock(`${registryPath}.lock`, async () => {
+    const registry = await readSessionRegistry(options);
+    const staleIds = new Set((registry.staleEntries ?? []).map((entry) => entry.sessionId));
+    const entries = options.pruneStale === false
+      ? registry.entries
+      : registry.entries.filter((entry) => !staleIds.has(entry.sessionId));
+    const backupDir = path.resolve(options.backupDir ?? cjoin(registry.home, 'registry', 'backups'));
+    await fs.mkdir(backupDir, { recursive: true });
+    const backupPath = cjoin(backupDir, registryBackupName());
+    if (await exists(registryPath)) await fs.copyFile(registryPath, backupPath);
+    else await atomicWriteText(backupPath, '');
+    const body = entries.length > 0 ? `${entries.map((entry) => JSON.stringify(entry)).join('\n')}\n` : '';
+    await atomicWriteText(registryPath, body);
+    return {
+      ok: true,
+      registryPath,
+      backupPath,
+      beforeEvents: registry.totalEvents,
+      afterEvents: entries.length,
+      kept: entries.length,
+      pruned: registry.entries.length - entries.length,
+      stale: registry.staleEntries.length,
+    };
+  });
+}
+
 export {
   normalizeSessionId,
+  compactSessionRegistry,
   readSessionRegistry,
   readSessionRegistryEntry,
   sessionRegistryFilePath,
+  setRegistryWriteEnabled,
   upsertSessionRegistryEntry,
 };

package/src/upgrade/fleet-mutation.js

@@ -0,0 +1,166 @@
+/*
+ * 核心功能
+ * 在 fleet 事务 staging 工作区中编排 update/setup/backfill，并把成功结果映射回兼容的 fleet 项目报告。
+ *
+ * 输入
+ * 接收 plannedAction、staging 项目路径、fleet options、workspace dependencies 与隔离 OPENPRD_HOME。
+ *
+ * 输出
+ * 返回统一 mutation 结果，或把成功结果写入原有 fleet item 字段。
+ *
+ * 定位
+ * 位于 fleet 外层循环和底层项目事务之间，保持 CLI 返回字段兼容。
+ *
+ * 依赖
+ * 依赖调用方注入的 setup/update/doctor/backfill workspace 函数，不直接导入应用层 openprd.js。
+ *
+ * 维护规则
+ * staging 永远关闭 user-scope 写入；新增动作时必须保证失败后不继续执行该项目的后续步骤。
+ */
+
+async function collectFleetProjectHealth(projectPath, options, doctorWorkspace) {
+  if (!doctorWorkspace) return { ok: true, errors: [] };
+  try {
+    const doctor = await doctorWorkspace(projectPath, {
+      tools: options.tools ?? 'all',
+      hookProfile: options.hookProfile,
+      enableUserCodexConfig: false,
+      codexHome: options.codexHome,
+      openprdHome: options.openprdHome,
+      docsContent: false,
+      sourceManuals: false,
+    });
+    return { ok: doctor.ok, errors: doctor.errors ?? [] };
+  } catch (error) {
+    return { ok: false, errors: [error instanceof Error ? error.message : String(error)] };
+  }
+}
+
+async function runStagedFleetMutation(plannedAction, projectPath, options, dependencies, staging) {
+  const stagedOptions = {
+    tools: options.tools ?? 'all',
+    hookProfile: options.hookProfile,
+    force: Boolean(options.force),
+    enableUserCodexConfig: false,
+    codexHome: options.codexHome,
+    openprdHome: staging.openprdHome,
+  };
+  if (plannedAction === 'update') {
+    const actionResult = await dependencies.updateAgentIntegrationWorkspace(projectPath, stagedOptions);
+    if (!actionResult.ok) {
+      return {
+        ok: false,
+        message: 'Staged OpenPrd update failed',
+        actionResult,
+        errors: actionResult.errors ?? [],
+        migration: { workspace: actionResult.migration ?? null, workUnits: null },
+      };
+    }
+    const backfill = dependencies.backfillWorkUnitsWorkspace
+      ? await dependencies.backfillWorkUnitsWorkspace(projectPath, {})
+      : { ok: true, changes: [], errors: [], totalVersions: 0, changedVersions: 0 };
+    if (!backfill.ok) {
+      return {
+        ok: false,
+        message: 'Staged work-unit backfill failed',
+        actionResult,
+        backfill,
+        errors: backfill.errors ?? [],
+        migration: {
+          workspace: actionResult.migration ?? null,
+          workUnits: { totalVersions: backfill.totalVersions, changedVersions: backfill.changedVersions, ok: false },
+        },
+      };
+    }
+    const health = await collectFleetProjectHealth(projectPath, {
+      ...options,
+      openprdHome: staging.openprdHome,
+    }, dependencies.doctorWorkspace);
+    return {
+      ok: true,
+      actionResult,
+      backfill,
+      health,
+      migration: {
+        workspace: actionResult.migration ?? null,
+        workUnits: {
+          totalVersions: backfill.totalVersions,
+          changedVersions: backfill.changedVersions,
+          ok: true,
+        },
+      },
+    };
+  }
+  if (plannedAction === 'setup') {
+    const actionResult = await dependencies.setupAgentIntegrationWorkspace(projectPath, stagedOptions);
+    return {
+      ok: actionResult.ok,
+      message: actionResult.ok ? null : 'Staged OpenPrd setup failed',
+      actionResult,
+      errors: actionResult.errors ?? actionResult.doctor?.errors ?? [],
+      migration: { workspace: actionResult.migration ?? null, workUnits: null },
+    };
+  }
+  if (plannedAction === 'backfill-work-units') {
+    if (!dependencies.backfillWorkUnitsWorkspace) {
+      return {
+        ok: false,
+        message: 'Missing fleet dependency: backfillWorkUnitsWorkspace',
+        errors: [],
+        migration: { workspace: null, workUnits: null },
+      };
+    }
+    const backfill = await dependencies.backfillWorkUnitsWorkspace(projectPath, {});
+    return {
+      ok: backfill.ok,
+      message: backfill.ok ? null : 'Staged work-unit backfill failed',
+      backfill,
+      errors: backfill.errors ?? [],
+      migration: {
+        workspace: null,
+        workUnits: {
+          totalVersions: backfill.totalVersions,
+          changedVersions: backfill.changedVersions,
+          ok: backfill.ok,
+        },
+      },
+    };
+  }
+  return { ok: false, message: `Unsupported staged fleet action: ${plannedAction}`, errors: [] };
+}
+
+function applySuccessfulFleetMutation(item, plannedAction, transaction) {
+  const mutation = transaction.mutationResult;
+  if (plannedAction === 'update') {
+    const update = mutation.actionResult;
+    const backfill = mutation.backfill;
+    item.status = 'updated';
+    item.registry = transaction.afterApplyResult?.registry ?? null;
+    item.changes = [
+      ...(update.migration?.changes ?? []).map((change) => ({ ...change, source: 'workspace' })),
+      ...(update.changes ?? []).map((change) => ({ ...change, source: 'agent' })),
+      ...(backfill.changes ?? []).map((change) => ({ ...change, source: 'work-unit' })),
+    ];
+    item.doctorOk = mutation.health.ok;
+    item.healthOk = mutation.health.ok;
+    item.healthErrors = mutation.health.errors;
+    item.workUnits = { totalVersions: backfill.totalVersions, changedVersions: backfill.changedVersions };
+    return;
+  }
+  if (plannedAction === 'setup') {
+    const setup = mutation.actionResult;
+    item.status = 'setup';
+    item.registry = transaction.afterApplyResult?.registry ?? null;
+    item.changes = [
+      ...(setup.migration?.changes ?? []).map((change) => ({ ...change, source: 'workspace' })),
+      ...(setup.changes ?? []).map((change) => ({ ...change, source: 'agent' })),
+    ];
+    return;
+  }
+  const backfill = mutation.backfill;
+  item.status = backfill.totalVersions > 0 ? 'backfilled' : 'skipped';
+  item.workUnits = { totalVersions: backfill.totalVersions, changedVersions: backfill.changedVersions };
+  item.changes = (backfill.changes ?? []).map((change) => ({ ...change, source: 'work-unit' }));
+}
+
+export { applySuccessfulFleetMutation, runStagedFleetMutation };