scene-capability-engine 3.6.32 → 3.6.36

package/lib/auto/recovery-selection-service.js

@@ -0,0 +1,52 @@
+async function resolveLatestRecoverableBatchSummary(projectPath, resumeStrategy = 'pending', dependencies = {}) {
+  const {
+    readCloseLoopBatchSummaryEntries,
+    loadCloseLoopBatchSummaryPayload,
+    buildCloseLoopBatchGoalsFromSummaryPayload
+  } = dependencies;
+  const entries = await readCloseLoopBatchSummaryEntries(projectPath);
+  for (const entry of entries) {
+    if (!entry || !entry.file) {
+      continue;
+    }
+    let loaded = null;
+    try {
+      loaded = await loadCloseLoopBatchSummaryPayload(projectPath, entry.file);
+      const goalsResult = await buildCloseLoopBatchGoalsFromSummaryPayload(
+        loaded.payload,
+        loaded.file,
+        projectPath,
+        'auto',
+        resumeStrategy
+      );
+      if (Array.isArray(goalsResult.goals) && goalsResult.goals.length > 0) {
+        return loaded;
+      }
+    } catch (_error) {
+      continue;
+    }
+  }
+  return null;
+}
+
+async function resolveLatestPendingControllerSession(projectPath, dependencies = {}) {
+  const {
+    readCloseLoopControllerSessionEntries,
+    loadCloseLoopControllerSessionPayload
+  } = dependencies;
+  const sessions = await readCloseLoopControllerSessionEntries(projectPath);
+  const pendingSession = sessions.find((session) => Number(session && session.pending_goals) > 0);
+  if (!pendingSession || !pendingSession.file) {
+    return null;
+  }
+  try {
+    return await loadCloseLoopControllerSessionPayload(projectPath, pendingSession.file);
+  } catch (_error) {
+    return null;
+  }
+}
+
+module.exports = {
+  resolveLatestRecoverableBatchSummary,
+  resolveLatestPendingControllerSession
+};

package/lib/auto/retention-policy.js

@@ -0,0 +1,98 @@
+function normalizeKeep(keepCandidate) {
+  if (keepCandidate === undefined || keepCandidate === null) {
+    return 20;
+  }
+  const parsed = Number(keepCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 1000) {
+    throw new Error('--keep must be an integer between 0 and 1000.');
+  }
+  return parsed;
+}
+
+function normalizeSpecKeep(keepCandidate, fallback = 200) {
+  if (keepCandidate === undefined || keepCandidate === null) {
+    return fallback;
+  }
+  const parsed = Number(keepCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 5000) {
+    throw new Error('--keep must be an integer between 0 and 5000.');
+  }
+  return parsed;
+}
+
+function normalizeOlderThanDays(daysCandidate) {
+  if (daysCandidate === undefined || daysCandidate === null) {
+    return null;
+  }
+  const parsed = Number(daysCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 36500) {
+    throw new Error('--older-than-days must be an integer between 0 and 36500.');
+  }
+  return parsed;
+}
+
+function normalizeSpecSessionProtectWindowDays(daysCandidate) {
+  if (daysCandidate === undefined || daysCandidate === null) {
+    return 7;
+  }
+  const parsed = Number(daysCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 36500) {
+    throw new Error('--spec-session-protect-window-days must be an integer between 0 and 36500.');
+  }
+  return parsed;
+}
+
+function normalizeSpecSessionMaxTotal(maxTotalCandidate) {
+  if (maxTotalCandidate === undefined || maxTotalCandidate === null) {
+    return null;
+  }
+  const parsed = Number(maxTotalCandidate);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 500000) {
+    throw new Error('--spec-session-max-total must be an integer between 1 and 500000.');
+  }
+  return parsed;
+}
+
+function normalizeSpecSessionMaxCreated(maxCreatedCandidate) {
+  if (maxCreatedCandidate === undefined || maxCreatedCandidate === null) {
+    return null;
+  }
+  const parsed = Number(maxCreatedCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 500000) {
+    throw new Error('--spec-session-max-created must be an integer between 0 and 500000.');
+  }
+  return parsed;
+}
+
+function normalizeSpecSessionMaxCreatedPerGoal(maxCreatedPerGoalCandidate) {
+  if (maxCreatedPerGoalCandidate === undefined || maxCreatedPerGoalCandidate === null) {
+    return null;
+  }
+  const parsed = Number(maxCreatedPerGoalCandidate);
+  if (Number.isNaN(parsed) || parsed < 0 || parsed > 1000) {
+    throw new Error('--spec-session-max-created-per-goal must be a number between 0 and 1000.');
+  }
+  return Number(parsed.toFixed(2));
+}
+
+function normalizeSpecSessionMaxDuplicateGoals(maxDuplicateGoalsCandidate) {
+  if (maxDuplicateGoalsCandidate === undefined || maxDuplicateGoalsCandidate === null) {
+    return null;
+  }
+  const parsed = Number(maxDuplicateGoalsCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 500000) {
+    throw new Error('--spec-session-max-duplicate-goals must be an integer between 0 and 500000.');
+  }
+  return parsed;
+}
+
+module.exports = {
+  normalizeKeep,
+  normalizeSpecKeep,
+  normalizeOlderThanDays,
+  normalizeSpecSessionProtectWindowDays,
+  normalizeSpecSessionMaxTotal,
+  normalizeSpecSessionMaxCreated,
+  normalizeSpecSessionMaxCreatedPerGoal,
+  normalizeSpecSessionMaxDuplicateGoals
+};

package/lib/auto/session-persistence-service.js

@@ -0,0 +1,106 @@
+async function maybePersistCloseLoopControllerSummary(summary, options, projectPath, dependencies = {}) {
+  const {
+    normalizeControllerSessionKeep,
+    normalizeControllerSessionOlderThanDays,
+    sanitizeBatchSessionId,
+    createControllerSessionId,
+    getCloseLoopControllerSessionDir,
+    pruneCloseLoopControllerSessions,
+    schemaVersion,
+    fs,
+    now = () => new Date()
+  } = dependencies;
+  if (options.controllerSession === false) {
+    return;
+  }
+
+  const keep = normalizeControllerSessionKeep(options.controllerSessionKeep);
+  const olderThanDays = normalizeControllerSessionOlderThanDays(options.controllerSessionOlderThanDays);
+  const requestedId = typeof options.controllerSessionId === 'string' && options.controllerSessionId.trim()
+    ? sanitizeBatchSessionId(options.controllerSessionId.trim())
+    : null;
+  const sessionId = requestedId || createControllerSessionId();
+  if (!sessionId) {
+    throw new Error('--controller-session-id is invalid after sanitization.');
+  }
+
+  const sessionDir = getCloseLoopControllerSessionDir(projectPath);
+  const sessionFile = require('path').join(sessionDir, `${sessionId}.json`);
+  summary.controller_session = { id: sessionId, file: sessionFile };
+  summary.schema_version = schemaVersion;
+
+  await fs.ensureDir(sessionDir);
+  const nowValue = now();
+  const updatedAt = nowValue instanceof Date ? nowValue.toISOString() : new Date(nowValue).toISOString();
+  await fs.writeJson(sessionFile, {
+    ...summary,
+    schema_version: schemaVersion,
+    controller_session: { id: sessionId, file: sessionFile },
+    updated_at: updatedAt
+  }, { spaces: 2 });
+
+  if (keep !== null || olderThanDays !== null) {
+    summary.controller_session_prune = await pruneCloseLoopControllerSessions(projectPath, {
+      keep: keep === null ? null : keep,
+      olderThanDays,
+      currentFile: sessionFile,
+      dryRun: false
+    });
+  }
+}
+
+async function maybePersistCloseLoopBatchSummary(summary, options, projectPath, dependencies = {}) {
+  const {
+    normalizeBatchSessionKeep,
+    normalizeBatchSessionOlderThanDays,
+    sanitizeBatchSessionId,
+    createBatchSessionId,
+    getCloseLoopBatchSummaryDir,
+    pruneCloseLoopBatchSummarySessions,
+    schemaVersion,
+    fs,
+    now = () => new Date()
+  } = dependencies;
+  if (options.batchSession === false) {
+    return;
+  }
+
+  const keep = normalizeBatchSessionKeep(options.batchSessionKeep);
+  const olderThanDays = normalizeBatchSessionOlderThanDays(options.batchSessionOlderThanDays);
+  const requestedId = typeof options.batchSessionId === 'string' && options.batchSessionId.trim()
+    ? sanitizeBatchSessionId(options.batchSessionId.trim())
+    : null;
+  const sessionId = requestedId || createBatchSessionId();
+  if (!sessionId) {
+    throw new Error('--batch-session-id is invalid after sanitization.');
+  }
+
+  const summaryDir = getCloseLoopBatchSummaryDir(projectPath);
+  const summaryFile = require('path').join(summaryDir, `${sessionId}.json`);
+  summary.batch_session = { id: sessionId, file: summaryFile };
+  summary.schema_version = schemaVersion;
+
+  await fs.ensureDir(summaryDir);
+  const nowValue = now();
+  const updatedAt = nowValue instanceof Date ? nowValue.toISOString() : new Date(nowValue).toISOString();
+  await fs.writeJson(summaryFile, {
+    ...summary,
+    schema_version: schemaVersion,
+    batch_session: { id: sessionId, file: summaryFile },
+    updated_at: updatedAt
+  }, { spaces: 2 });
+
+  if (keep !== null || olderThanDays !== null) {
+    summary.batch_session_prune = await pruneCloseLoopBatchSummarySessions(projectPath, {
+      keep: keep === null ? null : keep,
+      olderThanDays,
+      currentFile: summaryFile,
+      dryRun: false
+    });
+  }
+}
+
+module.exports = {
+  maybePersistCloseLoopControllerSummary,
+  maybePersistCloseLoopBatchSummary
+};

package/lib/auto/session-presenter.js

@@ -0,0 +1,105 @@
+function presentCloseLoopSessionList(projectPath, sessions, statusFilter, limit, buildStatusCounts, getCloseLoopSessionDir) {
+  const filteredSessions = Array.isArray(sessions) ? sessions : [];
+  return {
+    mode: 'auto-session-list',
+    session_dir: getCloseLoopSessionDir(projectPath),
+    total: filteredSessions.length,
+    status_filter: statusFilter,
+    status_counts: buildStatusCounts(filteredSessions),
+    sessions: filteredSessions.slice(0, limit)
+  };
+}
+
+function presentCloseLoopSessionStats(sessionDir, filteredSessions, statusFilter, days, cutoffMs, buildStatusCounts, buildMasterSpecCounts, isFailedStatus) {
+  // Backward compatibility: older callers omitted cutoffMs and passed builders directly.
+  if (typeof cutoffMs === 'function') {
+    isFailedStatus = buildMasterSpecCounts;
+    buildMasterSpecCounts = buildStatusCounts;
+    buildStatusCounts = cutoffMs;
+    cutoffMs = null;
+  }
+
+  let completedSessions = 0;
+  let failedSessions = 0;
+  let subSpecCountSum = 0;
+  let sessionsWithSubSpecs = 0;
+  for (const session of filteredSessions) {
+    const status = String(session && session.status || 'unknown').trim().toLowerCase();
+    if (status === 'completed') {
+      completedSessions += 1;
+    }
+    if (isFailedStatus(status)) {
+      failedSessions += 1;
+    }
+    const subSpecCount = Number(session && session.sub_spec_count);
+    if (Number.isFinite(subSpecCount)) {
+      subSpecCountSum += subSpecCount;
+      sessionsWithSubSpecs += 1;
+    }
+  }
+  const totalSessions = filteredSessions.length;
+  const completionRate = totalSessions > 0 ? Number(((completedSessions / totalSessions) * 100).toFixed(2)) : 0;
+  const failureRate = totalSessions > 0 ? Number(((failedSessions / totalSessions) * 100).toFixed(2)) : 0;
+  const masterSpecCounts = buildMasterSpecCounts(filteredSessions);
+  const latestSession = totalSessions > 0 ? filteredSessions[0] : null;
+  const oldestSession = totalSessions > 0 ? filteredSessions[totalSessions - 1] : null;
+  return {
+    mode: 'auto-session-stats',
+    session_dir: sessionDir,
+    criteria: {
+      days,
+      status_filter: statusFilter,
+      since: cutoffMs === null ? null : new Date(cutoffMs).toISOString()
+    },
+    total_sessions: totalSessions,
+    completed_sessions: completedSessions,
+    failed_sessions: failedSessions,
+    completion_rate_percent: completionRate,
+    failure_rate_percent: failureRate,
+    sub_spec_count_sum: subSpecCountSum,
+    average_sub_specs_per_session: sessionsWithSubSpecs > 0 ? Number((subSpecCountSum / sessionsWithSubSpecs).toFixed(2)) : 0,
+    unique_master_spec_count: Object.keys(masterSpecCounts).length,
+    master_spec_counts: masterSpecCounts,
+    status_counts: buildStatusCounts(filteredSessions),
+    latest_updated_at: latestSession ? latestSession.updated_at : null,
+    oldest_updated_at: oldestSession ? oldestSession.updated_at : null,
+    latest_sessions: filteredSessions.slice(0, 10).map((item) => ({
+      id: item.id,
+      status: item.status,
+      goal: item.goal,
+      master_spec: item.master_spec,
+      sub_spec_count: item.sub_spec_count,
+      updated_at: item.updated_at,
+      parse_error: item.parse_error
+    }))
+  };
+}
+
+function presentControllerSessionList(projectPath, filteredSessions, statusFilter, limit, buildStatusCounts, getCloseLoopControllerSessionDir) {
+  return {
+    mode: 'auto-controller-session-list',
+    session_dir: getCloseLoopControllerSessionDir(projectPath),
+    total: filteredSessions.length,
+    status_filter: statusFilter,
+    status_counts: buildStatusCounts(filteredSessions),
+    sessions: filteredSessions.slice(0, limit).map((item) => ({
+      id: item.id,
+      file: item.file,
+      status: item.status,
+      queue_file: item.queue_file,
+      queue_format: item.queue_format,
+      processed_goals: item.processed_goals,
+      pending_goals: item.pending_goals,
+      updated_at: item.updated_at,
+      parse_error: item.parse_error
+    }))
+  };
+}
+
+module.exports = {
+  presentCloseLoopSessionList,
+  presentCloseLoopSessionStats,
+  presentControllerSessionList
+};
+
+

package/lib/auto/session-prune-service.js

@@ -0,0 +1,190 @@
+async function pruneCloseLoopBatchSummarySessions(projectPath, policy = {}, dependencies = {}) {
+  const { readCloseLoopBatchSummaryEntries, getCloseLoopBatchSummaryDir, fs, now = () => Date.now() } = dependencies;
+  const keep = policy.keep;
+  const olderThanDays = policy.olderThanDays;
+  const currentFile = policy.currentFile || null;
+  const dryRun = Boolean(policy.dryRun);
+  const sessions = await readCloseLoopBatchSummaryEntries(projectPath);
+  const nowMs = typeof now === 'function' ? Number(now()) : Date.now();
+  const cutoffMs = olderThanDays === null ? null : nowMs - (olderThanDays * 24 * 60 * 60 * 1000);
+
+  const keepLimit = Number.isInteger(keep) ? keep : Number.POSITIVE_INFINITY;
+  const deletable = [];
+  for (let index = 0; index < sessions.length; index += 1) {
+    const session = sessions[index];
+    if (session.file === currentFile) {
+      continue;
+    }
+    const beyondKeep = Number.isFinite(keepLimit) ? index >= keepLimit : true;
+    const beyondAge = cutoffMs === null || session.mtime_ms < cutoffMs;
+    if (beyondKeep && beyondAge) {
+      deletable.push(session);
+    }
+  }
+
+  const deleted = [];
+  const errors = [];
+  if (!dryRun) {
+    for (const session of deletable) {
+      try {
+        await fs.remove(session.file);
+        deleted.push(session);
+      } catch (error) {
+        errors.push({ id: session.id, file: session.file, error: error.message });
+      }
+    }
+  }
+
+  return {
+    enabled: true,
+    session_dir: getCloseLoopBatchSummaryDir(projectPath),
+    dry_run: dryRun,
+    criteria: {
+      keep: Number.isFinite(keepLimit) ? keepLimit : null,
+      older_than_days: olderThanDays
+    },
+    total_sessions: sessions.length,
+    kept_sessions: sessions.length - deletable.length,
+    deleted_count: dryRun ? deletable.length : deleted.length,
+    candidates: deletable.map((item) => ({ id: item.id, file: item.file, status: item.status, updated_at: item.updated_at })),
+    errors
+  };
+}
+
+async function pruneCloseLoopControllerSessions(projectPath, policy = {}, dependencies = {}) {
+  const { readCloseLoopControllerSessionEntries, getCloseLoopControllerSessionDir, fs, now = () => Date.now() } = dependencies;
+  const keep = policy.keep;
+  const olderThanDays = policy.olderThanDays;
+  const currentFile = policy.currentFile || null;
+  const dryRun = Boolean(policy.dryRun);
+  const sessions = await readCloseLoopControllerSessionEntries(projectPath);
+  const nowMs = typeof now === 'function' ? Number(now()) : Date.now();
+  const cutoffMs = olderThanDays === null ? null : nowMs - (olderThanDays * 24 * 60 * 60 * 1000);
+
+  const keepLimit = Number.isInteger(keep) ? keep : Number.POSITIVE_INFINITY;
+  const deletable = [];
+  for (let index = 0; index < sessions.length; index += 1) {
+    const session = sessions[index];
+    if (session.file === currentFile) {
+      continue;
+    }
+    const beyondKeep = Number.isFinite(keepLimit) ? index >= keepLimit : true;
+    const beyondAge = cutoffMs === null || session.mtime_ms < cutoffMs;
+    if (beyondKeep && beyondAge) {
+      deletable.push(session);
+    }
+  }
+
+  const deleted = [];
+  const errors = [];
+  if (!dryRun) {
+    for (const session of deletable) {
+      try {
+        await fs.remove(session.file);
+        deleted.push(session);
+      } catch (error) {
+        errors.push({ id: session.id, file: session.file, error: error.message });
+      }
+    }
+  }
+
+  return {
+    enabled: true,
+    session_dir: getCloseLoopControllerSessionDir(projectPath),
+    dry_run: dryRun,
+    criteria: {
+      keep: Number.isFinite(keepLimit) ? keepLimit : null,
+      older_than_days: olderThanDays
+    },
+    total_sessions: sessions.length,
+    kept_sessions: sessions.length - deletable.length,
+    deleted_count: dryRun ? deletable.length : deleted.length,
+    candidates: deletable.map((item) => ({ id: item.id, file: item.file, status: item.status, updated_at: item.updated_at })),
+    errors
+  };
+}
+
+async function pruneCloseLoopSessions(projectPath, options = {}, dependencies = {}) {
+  const { normalizeKeep, normalizeOlderThanDays, readCloseLoopSessionEntries, getCloseLoopSessionDir, fs, now = () => Date.now() } = dependencies;
+  const keep = normalizeKeep(options.keep);
+  const olderThanDays = normalizeOlderThanDays(options.olderThanDays);
+  const dryRun = Boolean(options.dryRun);
+  const sessions = await readCloseLoopSessionEntries(projectPath);
+  const nowMs = typeof now === 'function' ? Number(now()) : Date.now();
+  const cutoffMs = olderThanDays === null ? null : nowMs - (olderThanDays * 24 * 60 * 60 * 1000);
+
+  const keepSet = new Set(sessions.slice(0, keep).map((session) => session.file));
+  const deletable = sessions.filter((session) => {
+    if (keepSet.has(session.file)) {
+      return false;
+    }
+    if (cutoffMs === null) {
+      return true;
+    }
+    return session.mtime_ms < cutoffMs;
+  });
+
+  const deleted = [];
+  const errors = [];
+  if (!dryRun) {
+    for (const session of deletable) {
+      try {
+        await fs.remove(session.file);
+        deleted.push(session);
+      } catch (error) {
+        errors.push({ id: session.id, file: session.file, error: error.message });
+      }
+    }
+  }
+
+  return {
+    mode: 'auto-session-prune',
+    session_dir: getCloseLoopSessionDir(projectPath),
+    dry_run: dryRun,
+    criteria: {
+      keep,
+      older_than_days: olderThanDays
+    },
+    total_sessions: sessions.length,
+    kept_sessions: sessions.length - deletable.length,
+    deleted_count: dryRun ? deletable.length : deleted.length,
+    candidates: deletable.map((item) => ({ id: item.id, file: item.file, status: item.status, updated_at: item.updated_at })),
+    errors
+  };
+}
+
+async function pruneCloseLoopBatchSummarySessionsCli(projectPath, options = {}, dependencies = {}) {
+  const { normalizeKeep, normalizeOlderThanDays, pruneCloseLoopBatchSummarySessions } = dependencies;
+  const keep = normalizeKeep(options.keep);
+  const olderThanDays = normalizeOlderThanDays(options.olderThanDays);
+  const dryRun = Boolean(options.dryRun);
+  const result = await pruneCloseLoopBatchSummarySessions(projectPath, {
+    keep,
+    olderThanDays,
+    currentFile: null,
+    dryRun
+  });
+  return { mode: 'auto-batch-session-prune', ...result };
+}
+
+async function pruneCloseLoopControllerSessionsCli(projectPath, options = {}, dependencies = {}) {
+  const { normalizeKeep, normalizeOlderThanDays, pruneCloseLoopControllerSessions } = dependencies;
+  const keep = normalizeKeep(options.keep);
+  const olderThanDays = normalizeOlderThanDays(options.olderThanDays);
+  const dryRun = Boolean(options.dryRun);
+  const result = await pruneCloseLoopControllerSessions(projectPath, {
+    keep,
+    olderThanDays,
+    currentFile: null,
+    dryRun
+  });
+  return { mode: 'auto-controller-session-prune', ...result };
+}
+
+module.exports = {
+  pruneCloseLoopBatchSummarySessions,
+  pruneCloseLoopControllerSessions,
+  pruneCloseLoopSessions,
+  pruneCloseLoopBatchSummarySessionsCli,
+  pruneCloseLoopControllerSessionsCli
+};