codex-overleaf-link 2.4.0 → 2.5.0

package/extension/src/content/writebackPlan.js

@@ -0,0 +1,231 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('WritebackPlan', [], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function () {
+  'use strict';
+
+  // Input validation, user approval, and audit projection precede page mutation.
+  function create(deps = {}) {
+    const { tx, tr, normalizeSafeProjectPath, GovernanceRules, getGovernanceRulesForCurrentProject,
+      showPluginConfirm, formatOperationFiles, getAppliedEntries, getSkippedEntries } = deps;
+
+  function partitionUnsafeProjectPathOperations(operations = []) {
+    const safe = [];
+    const skipped = [];
+    for (const operation of operations || []) {
+      const normalized = normalizeOperationProjectPaths(operation);
+      const invalid = getInvalidOperationProjectPath(normalized);
+      if (invalid) {
+        skipped.push({
+          operation: normalized,
+          result: {
+            ok: false,
+            code: 'invalid_project_path',
+            reason: tx(`Invalid ${invalid}. Codex did not write this file.`, `路径无效：${invalid}。Codex 没有写入这个文件。`)
+          }
+        });
+        continue;
+      }
+      safe.push(normalized);
+    }
+    return { safe, skipped };
+  }
+
+  function normalizeOperationProjectPaths(operation = {}) {
+    if (!operation || typeof operation !== 'object') {
+      return operation;
+    }
+    const normalized = { ...operation };
+    if (typeof operation.path === 'string') {
+      normalized.path = normalizeSafeProjectPath(operation.path);
+      if (!normalized.path) {
+        normalized.invalidProjectPath = true;
+      }
+    }
+    if (typeof operation.to === 'string') {
+      normalized.to = normalizeSafeProjectPath(operation.to);
+      if (!normalized.to) {
+        normalized.invalidProjectDestinationPath = true;
+      }
+    }
+    if (typeof operation.destinationPath === 'string') {
+      normalized.destinationPath = normalizeSafeProjectPath(operation.destinationPath);
+      if (!normalized.destinationPath) {
+        normalized.invalidProjectDestinationPath = true;
+      }
+    }
+    return normalized;
+  }
+
+  function getInvalidOperationProjectPath(operation = {}) {
+    if (operation.invalidProjectPath || (requiresOperationPath(operation) && !operation.path)) {
+      return 'operation path';
+    }
+    if (operation.invalidProjectDestinationPath || (requiresOperationDestinationPath(operation) && !(operation.to || operation.destinationPath))) {
+      return 'operation destination path';
+    }
+    return '';
+  }
+
+  function requiresOperationPath(operation = {}) {
+    return ['edit', 'create', 'delete', 'rename', 'move', 'binary-create', 'overwrite-binary'].includes(operation.type);
+  }
+
+  function requiresOperationDestinationPath(operation = {}) {
+    return operation.type === 'rename' || operation.type === 'move';
+  }
+
+
+  function evaluateGovernedOperations(operations = []) {
+    if (!GovernanceRules?.evaluateGovernedOperations) {
+      return { allowed: operations || [], blocked: [], rules: getGovernanceRulesForCurrentProject() };
+    }
+    return GovernanceRules.evaluateGovernedOperations(operations, getGovernanceRulesForCurrentProject());
+  }
+
+  function buildGovernanceSkippedApplyResult(blockedItems = []) {
+    return {
+      ok: blockedItems.length === 0,
+      applied: [],
+      skipped: (blockedItems || []).map(item => ({
+        operation: item.operation,
+        result: {
+          ok: false,
+          code: 'governance_blocked',
+          reason: formatGovernanceBlockedReason(item),
+          reasonKey: item.reason || 'governance_blocked'
+        }
+      }))
+    };
+  }
+
+  function formatGovernanceBlockedReason(item = {}) {
+    if (item.reason === 'readonly') {
+      return tx(
+        'Project governance marked this path read-only, so Codex did not write it.',
+        '项目治理规则将此路径标记为只读，因此 Codex 没有写入。'
+      );
+    }
+    if (item.reason === 'writable_allowlist') {
+      return tx(
+        'Project governance allows writes only to configured writable patterns, and this path is outside that allowlist.',
+        '项目治理规则只允许写入配置的可写路径，此路径不在允许范围内。'
+      );
+    }
+    return tx('Project governance blocked this write.', '项目治理规则阻止了此写入。');
+  }
+
+  function filterSyncChangesByOperations(syncChanges = [], operations = []) {
+    const allowedPaths = new Set((operations || []).map(operation => operation.path).filter(Boolean));
+    return (syncChanges || []).filter(change => allowedPaths.has(change?.path));
+  }
+
+  function mergeApplyResultSkipped(result = {}, skipped = []) {
+    if (!skipped.length) {
+      return result;
+    }
+    return {
+      ...(result || {}),
+      ok: false,
+      applied: Array.isArray(result?.applied) ? result.applied : [],
+      skipped: [
+        ...getSkippedEntries(result),
+        ...skipped
+      ]
+    };
+  }
+
+  async function confirmBinaryOperations(operations = []) {
+    const binaryOperations = (operations || []).filter(operation => operation.type === 'binary-create' || operation.type === 'overwrite-binary');
+    if (!binaryOperations.length) {
+      return { operations, skipped: [] };
+    }
+    const approved = await showPluginConfirm({
+      title: tr('binaryAssetConfirmTitle'),
+      message: tr('binaryAssetConfirmMessage', { files: formatOperationFiles(binaryOperations) }),
+      confirmLabel: tr('binaryAssetConfirm'),
+      cancelLabel: tr('binaryAssetCancel'),
+      destructive: true
+    });
+    if (approved) {
+      return { operations, skipped: [] };
+    }
+    return {
+      operations: operations.filter(operation => operation.type !== 'binary-create' && operation.type !== 'overwrite-binary'),
+      skipped: binaryOperations.map(operation => ({
+        operation,
+        result: {
+          ok: false,
+          code: 'binary_confirmation_rejected',
+          reason: tx('Binary asset writeback requires explicit confirmation and was skipped.', '二进制资源写回需要显式确认，已跳过。')
+        }
+      }))
+    };
+  }
+
+  function buildAuditDiffSummary(operations = []) {
+    const changedFiles = new Set();
+    let binaryFilesChanged = 0;
+    for (const operation of operations || []) {
+      if (operation?.path) {
+        changedFiles.add(operation.path);
+      }
+      if (operation?.type === 'binary-create' || operation?.type === 'overwrite-binary') {
+        binaryFilesChanged++;
+      }
+    }
+    return {
+      filesChanged: changedFiles.size,
+      additions: 0,
+      deletions: 0,
+      binaryFilesChanged
+    };
+  }
+
+  function buildAuditSummaryFromApply({ operations = [], applyResults = [], blockedFiles = [], resultStatus = 'completed', saveVerification = null } = {}) {
+    const appliedFiles = [];
+    const skippedFiles = [];
+    for (const result of applyResults || []) {
+      for (const item of getAppliedEntries(result)) {
+        appliedFiles.push(summarizeOperationForAudit(item.operation, item.result, 'applied'));
+      }
+      for (const item of getSkippedEntries(result)) {
+        skippedFiles.push(summarizeOperationForAudit(item.operation, item.result, 'skipped'));
+      }
+    }
+    return {
+      changedFiles: (operations || []).map(operation => summarizeOperationForAudit(operation, {}, 'changed')),
+      ['diffSummary']: buildAuditDiffSummary(operations),
+      blockedFiles,
+      appliedFiles,
+      skippedFiles,
+      resultStatus,
+      saveVerification
+    };
+  }
+
+  // Tolerates `operation` and `result` being null in addition to undefined.
+  // Default-parameter values fire only for `undefined`, but the v1.3.8
+  // write-guard (pageBridge.runWriteGuard / writebackRouter.checkWritebackRunProjectId)
+  // emits batch-level skips with `operation: null` — there is no specific
+  // op to attribute the block to. Without this normalization the audit pass
+  // crashed with "Cannot read properties of null (reading 'path')", the
+  // outer-catch swallowed the partial-sync conclusion, and the user saw the
+  // misleading "local Codex returned no usable result" fallback.
+  function summarizeOperationForAudit(operation, result, status = '') {
+    const op = operation || {};
+    const res = result || {};
+    return {
+      path: op.path || op.from || op.to || '',
+      destinationPath: op.destinationPath || op.to || '',
+      type: op.type || '',
+      reason: res.reasonKey || res.code || res.reason || op.reasonKey || op.reason || '',
+      status,
+      size: op.size
+    };
+  }
+
+    return { partitionUnsafeProjectPathOperations, normalizeOperationProjectPaths, getInvalidOperationProjectPath, evaluateGovernedOperations, buildGovernanceSkippedApplyResult, filterSyncChangesByOperations, mergeApplyResultSkipped, confirmBinaryOperations, buildAuditSummaryFromApply, summarizeOperationForAudit };
+  }
+  return { create };
+});

package/extension/src/content/writebackRecovery.js

@@ -0,0 +1,122 @@
+(function (root, factory) {
+  root.CodexOverleafModuleRegistry.define('WritebackRecovery', ['WritebackIntent', 'UndoOperations'], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function (Intent, Undo) {
+  'use strict';
+  function create(deps) {
+    let recovery = null;
+    const owner = () => ({ projectId: deps.getProjectId(), accountScopeId: deps.getAccountScopeId() });
+    const current = scope => scope.projectId === deps.getProjectId() && scope.accountScopeId === deps.getAccountScopeId();
+    const runs = () => (deps.getState()?.sessions || []).flatMap(session => (session.runs || []).map(run => ({ session, run })));
+    async function prepare(input) {
+      const view = deps.getRun(), scope = owner();
+      const run = view && deps.findRun(view.recordId, view.sessionId);
+      if (!run || !scope.accountScopeId || input.runProjectId !== scope.projectId
+        || view.runProjectId !== scope.projectId) throw new Error('Writeback ownership changed before dispatch.');
+      const pending = Intent.normalize({
+        ...scope, id: crypto.randomUUID(), sessionId: view.sessionId, runId: run.id,
+        createdAt: new Date().toISOString(), operations: input.operations, baseFiles: input.baseFiles,
+        requireReviewing: input.requireReviewing
+      });
+      if (!pending) throw new Error('This change exceeds the recoverable writeback limit. Split it into smaller changes.');
+      for (const op of pending.operations) {
+        if (op.type === 'edit' && !pending.baseFiles.some(file => file.path === op.path)) {
+          throw new Error('The original content of ' + op.path + ' is unavailable. Refresh the project before writing.');
+        }
+      }
+      run.pendingWriteback = pending;
+      await deps.save();
+      if (!current(scope)) throw new Error('Project changed before writeback dispatch.');
+      const stored = await deps.StorageDb.getRecord('sessions', view.sessionId);
+      if (stored?.accountScopeId !== scope.accountScopeId || stored?.projectId !== scope.projectId
+        || !(stored.runs || []).some(item => item.id === run.id && item.pendingWriteback?.id === pending.id)) {
+        throw new Error('The writeback recovery record could not be saved. No write was dispatched.');
+      }
+      return pending.id;
+    }
+    async function settle(input, result) {
+      const view = deps.getRun(), run = view && deps.findRun(view.recordId, view.sessionId);
+      if (!run?.pendingWriteback || run.pendingWriteback.projectId !== input.runProjectId) return;
+      const uncertain = result?.receiptUnconfirmed === true || (result?.skipped || []).some(entry => {
+        const item = entry.result || entry; return item.changedDocument === true || item.failure?.changedDocument === true;
+      });
+      // Volatile marker only. The intent remains durable until the mature
+      // action checkpoint has been recorded by the orchestrator.
+      run.writebackResultKnown = !uncertain;
+    }
+    function checkpointRecorded(run) {
+      if (run?.writebackResultKnown === true) {
+        delete run.pendingWriteback; delete run.writebackResultKnown;
+      }
+    }
+    async function recover() {
+      if (recovery) return recovery;
+      recovery = reconcile().finally(() => { recovery = null; });
+      return recovery;
+    }
+    async function reconcile() {
+      if (deps.getRun()) return false;
+      const scope = owner();
+      const pending = runs().filter(({ run }) => run.pendingWriteback
+        && run.pendingWriteback.projectId === scope.projectId && run.pendingWriteback.accountScopeId === scope.accountScopeId);
+      if (!pending.length) return true;
+      const snapshot = await deps.readProject();
+      if (!current(scope) || !snapshot?.capabilities?.fullProjectSnapshot) return false;
+      const observed = new Map((snapshot.files || []).map(file => [file.path, file]));
+      for (const { session, run } of pending) {
+        const intent = Intent.normalize(run.pendingWriteback);
+        if (!intent || intent.sessionId !== session.id || intent.runId !== run.id) continue;
+        const before = new Map(intent.baseFiles.map(file => [file.path, file.content]));
+        const after = Intent.expectedFiles(intent);
+        const applied = [], untouched = [], unknown = [];
+        for (const operation of intent.operations) {
+          const paths = [operation.path, operation.to].filter(Boolean);
+          if (operation.type.includes('binary')) {
+            unknown.push(operation.path); continue;
+          }
+          const matches = map => paths.every(path => map.has(path)
+            ? typeof observed.get(path)?.content === 'string' && observed.get(path).content === map.get(path)
+            : !observed.has(path));
+          if (matches(before)) untouched.push(operation.path);
+          else if (matches(after)) applied.push(operation);
+          else unknown.push(operation.path);
+        }
+        if (!current(scope)) return false;
+        const retained = Array.isArray(run.appliedOperations) ? run.appliedOperations : [];
+        const knownPaths = new Set(retained.map(op => op.path));
+        run.appliedOperations = [...retained, ...applied.filter(op => !knownPaths.has(op.path))];
+        if (applied.length) {
+          run.changedDocument = true;
+          if (intent.requireReviewing) {
+            // Text readback cannot recreate native tracked-change identities.
+            // Preserve real refs if already captured; never fabricate Accept.
+            run.undoExpectedFiles = intent.baseFiles;
+            run.trackedChangeStatus = ['accepted', 'rejected'].includes(run.trackedChangeStatus)
+              ? run.trackedChangeStatus : 'needs_review';
+          } else {
+            const undo = Undo.buildUndoCheckpoint({ files: intent.baseFiles }, run.appliedOperations);
+            run.undoOperations = undo.undoOperations; run.undoBaseFiles = undo.undoBaseFiles;
+            run.undoExpectedFiles = intent.baseFiles;
+          }
+        }
+        if (!unknown.length) delete run.pendingWriteback;
+        run.status = applied.length || unknown.length ? 'needs_review_after_navigation' : 'interrupted';
+        run.statusText = deps.tx('Writeback checked after refresh', '已核对刷新前的写入');
+        const text = deps.tx(
+          'Writeback recovery: ' + applied.length + ' confirmed changed, ' + untouched.length + ' unchanged, ' + unknown.length + ' require inspection.',
+          '写入核对：' + applied.length + ' 项已确认修改，' + untouched.length + ' 项未修改，' + unknown.length + ' 项需要检查。'
+        );
+        run.events = [...(run.events || []).filter(event => event.recoveryIntentId !== intent.id), {
+          kind: 'activity', title: text, status: unknown.length ? 'warning' : 'completed',
+          timestamp: new Date().toISOString(), recoveryIntentId: intent.id,
+          activity: { v: 1, kind: 'notice', id: 'writeback-recovery:' + intent.id, state: unknown.length ? 'warning' : 'info' }
+        }].slice(-300);
+        session.updatedAt = new Date().toISOString();
+      }
+      await deps.save();
+      if (current(scope)) deps.refresh();
+      return !runs().some(({ run }) => run.pendingWriteback?.projectId === scope.projectId);
+    }
+    return { prepare, settle, checkpointRecorded, recover };
+  }
+  return { create };
+});