helloagents 3.0.2-beta.1 → 3.0.7

package/scripts/advisor-state.mjs

@@ -0,0 +1,222 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+import { appendReplayEvent } from './replay-state.mjs'
+import { captureWorkspaceFingerprint } from './verify-state.mjs'
+
+export const ADVISOR_EVIDENCE_FILE_NAME = '.ralph-advisor.json'
+const ADVISOR_EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+const VALID_ADVISOR_OUTCOMES = new Set(['clean', 'findings'])
+const VALID_SOURCES = new Set(['claude', 'codex', 'gemini'])
+
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) return []
+  return [...new Set(values.map((value) => (typeof value === 'string' ? value.trim() : '')).filter(Boolean))]
+}
+
+function normalizeSources(values) {
+  return normalizeStringArray(values).filter((value) => VALID_SOURCES.has(value))
+}
+
+function normalizeOutcome(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_ADVISOR_OUTCOMES.has(normalized) ? normalized : ''
+}
+
+export function getAdvisorEvidencePath(cwd) {
+  return join(cwd, '.helloagents', ADVISOR_EVIDENCE_FILE_NAME)
+}
+
+export function readAdvisorEvidence(cwd) {
+  try {
+    return JSON.parse(readFileSync(getAdvisorEvidencePath(cwd), 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+export function clearAdvisorEvidence(cwd) {
+  rmSync(getAdvisorEvidencePath(cwd), { force: true })
+}
+
+export function normalizeAdvisorEvidence(input = {}) {
+  return {
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    reason: typeof input.reason === 'string' ? input.reason.trim() : '',
+    focus: normalizeStringArray(input.focus),
+    preferredSources: normalizeSources(input.preferredSources),
+    consultedSources: normalizeSources(input.consultedSources),
+    outcome: normalizeOutcome(input.outcome),
+    summary: typeof input.summary === 'string' ? input.summary.trim() : '',
+    findings: normalizeStringArray(input.findings),
+    recommendations: normalizeStringArray(input.recommendations),
+  }
+}
+
+export function writeAdvisorEvidence(cwd, input = {}) {
+  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+  const normalized = normalizeAdvisorEvidence(input)
+  const payload = {
+    updatedAt: new Date().toISOString(),
+    ...normalized,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeFileSync(getAdvisorEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  appendReplayEvent(cwd, {
+    event: 'advisor_evidence_written',
+    source: normalized.source,
+    skillName: normalized.originCommand,
+    details: {
+      reason: normalized.reason,
+      focus: normalized.focus,
+      preferredSources: normalized.preferredSources,
+      consultedSources: normalized.consultedSources,
+      outcome: normalized.outcome,
+    },
+    artifacts: ['.helloagents/.ralph-advisor.json'],
+  })
+  return payload
+}
+
+function readRequiredAdvisorEvidence(cwd, required) {
+  if (!required) {
+    return {
+      required: false,
+      status: 'not-applicable',
+    }
+  }
+
+  const evidence = readAdvisorEvidence(cwd)
+  if (evidence) return { evidence }
+  return {
+    error: {
+      required: true,
+      status: 'missing',
+      details: ['missing advisor evidence required by the active contract'],
+    },
+  }
+}
+
+function validateAdvisorTimestamp(evidence, now) {
+  const updatedAt = Date.parse(evidence.updatedAt || '')
+  if (!Number.isFinite(updatedAt)) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['advisor evidence timestamp is invalid'],
+    }
+  }
+  if (now - updatedAt > ADVISOR_EVIDENCE_MAX_AGE_MS) {
+    return {
+      required: true,
+      status: 'stale-time',
+      evidence,
+      details: ['advisor evidence is older than 30 minutes'],
+    }
+  }
+  return null
+}
+
+function validateAdvisorFingerprint(cwd, evidence) {
+  const currentFingerprint = captureWorkspaceFingerprint(cwd)
+  if (
+    currentFingerprint.available
+    && evidence.fingerprint?.available
+    && currentFingerprint.combined !== evidence.fingerprint.combined
+  ) {
+    return {
+      required: true,
+      status: 'stale-diff',
+      evidence,
+      details: ['workspace diff changed after the last advisor evidence'],
+    }
+  }
+  return null
+}
+
+function validateAdvisorContent(evidence, focus = []) {
+  if (!normalizeOutcome(evidence.outcome) || !String(evidence.summary || '').trim() || !String(evidence.reason || '').trim()) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['advisor evidence must record explicit outcome, reason, and summary'],
+    }
+  }
+  if (normalizeSources(evidence.consultedSources).length === 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['advisor evidence must record at least one consulted source'],
+    }
+  }
+  if (normalizeStringArray(focus).length > 0 && normalizeStringArray(evidence.focus).length === 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['advisor evidence must retain the requested advisor focus'],
+    }
+  }
+  if (normalizeOutcome(evidence.outcome) !== 'clean') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      details: ['latest advisor evidence still records blocking findings'],
+    }
+  }
+  return null
+}
+
+export function getAdvisorEvidenceStatus(cwd, { required = false, focus = [], now = Date.now() } = {}) {
+  const requiredEvidence = readRequiredAdvisorEvidence(cwd, required)
+  if ('status' in requiredEvidence) return requiredEvidence
+  if (requiredEvidence.error) return requiredEvidence.error
+
+  const { evidence } = requiredEvidence
+  const timestampError = validateAdvisorTimestamp(evidence, now)
+  if (timestampError) return timestampError
+
+  const fingerprintError = validateAdvisorFingerprint(cwd, evidence)
+  if (fingerprintError) return fingerprintError
+
+  const contentError = validateAdvisorContent(evidence, focus)
+  if (contentError) return contentError
+
+  return {
+    required: true,
+    status: 'valid',
+    evidence,
+  }
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  if (command !== 'write') return
+
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+  const payload = writeAdvisorEvidence(cwd, input)
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getAdvisorEvidencePath(cwd),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/capability-registry.mjs

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs'
+
+import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
+import { describeProjectStoreFile, getProjectDesignContractPath } from './project-storage.mjs'
+import { getWorkflowRecommendation, getWorkflowSnapshot } from './workflow-state.mjs'
+
+function getPrimaryPlan(snapshot) {
+  return snapshot.activePlans[0] || snapshot.plans[0] || null
+}
+
+export function selectCapabilities({ cwd, skillName = '' }) {
+  const snapshot = getWorkflowSnapshot(cwd)
+  const recommendation = getWorkflowRecommendation(cwd)
+  const plan = getPrimaryPlan(snapshot)
+  const advisorRequirement = getAdvisorRequirement(plan?.contract)
+  const visualRequirement = getVisualValidationRequirement(plan?.contract)
+  const capabilities = []
+
+  if (skillName === 'plan' || skillName === 'prd' || recommendation?.nextCommand === 'plan') {
+    capabilities.push({
+      id: 'plan-contract',
+      description: '结构化 contract：仅在规划/PRD 场景使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在 prose。',
+    })
+  }
+  if (advisorRequirement.required) {
+    capabilities.push({
+      id: 'advisor-artifact',
+      description: advisorRequirement.styleRequired
+        ? '风格 advisor：当前 UI contract 要求进入收尾前复查设计方向，并复用 `.helloagents/.ralph-advisor.json` 记录 reason、focus、consultedSources 与结论。'
+        : '独立 advisor：当前 contract 要求进入收尾前写 `.helloagents/.ralph-advisor.json`，记录 advisor reason、focus、consultedSources 与结论。',
+    })
+  }
+  if (plan?.contract?.verifyMode === 'review-first') {
+    capabilities.push({
+      id: 'review-evaluator',
+      description: '审查优先：当前验证主路径是 review-first，先做 hello-review，再做 hello-verify。',
+    })
+  }
+  if (plan?.contract?.ui?.required || existsSync(getProjectDesignContractPath(cwd))) {
+    capabilities.push({
+      id: 'design-contract',
+      description: `UI 契约：仅在 UI 场景按需读取当前 plan.md / prd/03-ui-design.md、${describeProjectStoreFile(cwd, 'DESIGN.md')} 与 hello-ui，不全局常驻。`,
+    })
+  }
+  if (visualRequirement.required) {
+    capabilities.push({
+      id: 'visual-evaluator',
+      description: '视觉验收：当前 UI contract 要求进入收尾前写 `.helloagents/.ralph-visual.json`，记录 tooling、screensChecked、statesChecked、status 与 summary。',
+    })
+  }
+
+  return capabilities
+}
+
+export function buildCapabilityHint({ cwd, skillName = '' }) {
+  const capabilities = selectCapabilities({ cwd, skillName })
+  if (capabilities.length === 0) return ''
+  return `按需能力：${capabilities.map((entry) => `${entry.id}=${entry.description}`).join(' ')}`
+}

package/scripts/cli-codex-backup.mjs

@@ -0,0 +1,59 @@
+import { copyFileSync, existsSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { removeIfExists, safeRead } from './cli-utils.mjs'
+
+const CODEX_BACKUP_TIMESTAMP_RE = /^\d{8}-\d{6}$/
+
+function formatBackupTimestamp(date = new Date()) {
+  const pad = (value, size = 2) => String(value).padStart(size, '0')
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+}
+
+export function createTimestampedBackupPath(filePath, backupBaseName) {
+  return join(dirname(filePath), `${backupBaseName}_${formatBackupTimestamp()}.bak`)
+}
+
+function listTimestampedBackups(directory, backupBaseName) {
+  if (!existsSync(directory)) return []
+  return readdirSync(directory)
+    .filter((name) => name.startsWith(`${backupBaseName}_`) && name.endsWith('.bak'))
+    .filter((name) => CODEX_BACKUP_TIMESTAMP_RE.test(name.slice(backupBaseName.length + 1, -4)))
+    .sort()
+}
+
+function getLatestTimestampedBackupPath(filePath, backupBaseName) {
+  const backups = listTimestampedBackups(dirname(filePath), backupBaseName)
+  const latest = backups.at(-1)
+  return latest ? join(dirname(filePath), latest) : ''
+}
+
+function readLatestTimestampedBackup(filePath, backupBaseName) {
+  const backupPath = getLatestTimestampedBackupPath(filePath, backupBaseName)
+  return backupPath ? safeRead(backupPath) || '' : ''
+}
+
+function removeLatestTimestampedBackup(filePath, backupBaseName) {
+  const backupPath = getLatestTimestampedBackupPath(filePath, backupBaseName)
+  if (backupPath) removeIfExists(backupPath)
+}
+
+export function ensureTimestampedBackup(filePath, backupBaseName) {
+  if (!existsSync(filePath)) return ''
+  const existingBackup = getLatestTimestampedBackupPath(filePath, backupBaseName)
+  if (existingBackup) return existingBackup
+  const backupPath = createTimestampedBackupPath(filePath, backupBaseName)
+  copyFileSync(filePath, backupPath)
+  return backupPath
+}
+
+export function readCodexBackup(filePath, backupBaseName) {
+  const latest = readLatestTimestampedBackup(filePath, backupBaseName)
+  if (latest) return latest
+  return safeRead(`${filePath}.bak`) || ''
+}
+
+export function removeCodexBackup(filePath, backupBaseName) {
+  removeLatestTimestampedBackup(filePath, backupBaseName)
+  removeIfExists(`${filePath}.bak`)
+}

package/scripts/cli-codex-config.mjs

@@ -0,0 +1,100 @@
+import {
+  createTimestampedBackupPath,
+  readCodexBackup,
+  removeCodexBackup,
+} from './cli-codex-backup.mjs'
+import { safeWrite } from './cli-utils.mjs'
+import {
+  ensureTopLevelTomlBlock,
+  readTopLevelTomlBlock,
+  removeTopLevelTomlBlock,
+  stripTomlSection,
+  upsertTopLevelTomlBlock,
+} from './cli-toml.mjs'
+
+export const CODEX_PLUGIN_CONFIG_HEADER = '[plugins."helloagents@local-plugins"]'
+export const CODEX_MANAGED_TOML_COMMENT = '# helloagents-managed'
+const CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME = 'developer_instructions'
+
+export const CODEX_DEVELOPER_INSTRUCTIONS = `CRITICAL: These are HelloAGENTS global defaults for Codex. Use them as the baseline for main-agent behavior. Spawned sub-agents should focus on the delegated task unless they are explicitly required to follow main-agent-only workflow.
+If the current workspace contains a project-level AGENTS.md or other repo-specific instructions, treat those as the more specific and authoritative instructions. Use these global defaults only where they do not conflict. Standby/global behavior is determined by the active workspace instructions, not by this global default block.
+If work was already in progress and earlier context was compressed, first restore the active project state from the most relevant project state files or other project-local context artifacts, then continue from the actual interruption point without restarting the workflow or repeating completed steps.`
+
+export function isManagedCodexStandbyInstructionPath(normalized = '') {
+  return /\/\.codex\/helloagents\/bootstrap-lite\.md/i.test(normalized)
+}
+
+export function isManagedCodexGlobalInstructionPath(normalized = '') {
+  return /\/plugins\/helloagents\/AGENTS\.md/i.test(normalized)
+    || /\/plugins\/helloagents\/bootstrap\.md/i.test(normalized)
+}
+
+export function upsertCodexPluginConfig(text) {
+  const stripped = stripTomlSection(text, CODEX_PLUGIN_CONFIG_HEADER).text.trimEnd()
+  const block = `${CODEX_PLUGIN_CONFIG_HEADER}\nenabled = true`
+  return stripped ? `${stripped}\n\n${block}\n` : `${block}\n`
+}
+
+export function removeCodexPluginConfig(text) {
+  return stripTomlSection(text, CODEX_PLUGIN_CONFIG_HEADER).text
+}
+
+export function isManagedCodexModelInstruction(line = '') {
+  const normalized = String(line || '').replace(/\\/g, '/')
+  return line.includes('model_instructions_file')
+    && (
+      line.includes(CODEX_MANAGED_TOML_COMMENT)
+      || isManagedCodexStandbyInstructionPath(normalized)
+      || isManagedCodexGlobalInstructionPath(normalized)
+    )
+}
+
+export function isManagedCodexNotify(line = '') {
+  return line.includes('codex-notify') || (line.includes('helloagents') && line.includes('notify'))
+}
+
+export function isManagedCodexBackupInstruction(line = '') {
+  return line.includes(CODEX_MANAGED_TOML_COMMENT)
+}
+
+function formatManagedCodexDeveloperInstructions() {
+  return `"""\n${CODEX_DEVELOPER_INSTRUCTIONS}\n"""`
+}
+
+function backupUserCodexDeveloperInstructions(configPath, existingBlock) {
+  if (!existingBlock || existingBlock.includes('HelloAGENTS')) return
+  safeWrite(createTimestampedBackupPath(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME), `${existingBlock}\n`)
+}
+
+function sanitizeCodexDeveloperInstructionsBackup(block = '') {
+  const normalized = String(block || '').trim()
+  if (!normalized.startsWith('developer_instructions =')) return ''
+  if (normalized.includes(CODEX_DEVELOPER_INSTRUCTIONS)) return ''
+  return normalized
+}
+
+function readCodexDeveloperInstructionsBackup(configPath) {
+  return sanitizeCodexDeveloperInstructionsBackup(
+    readCodexBackup(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME),
+  )
+}
+
+function removeCodexDeveloperInstructionsBackup(configPath) {
+  removeCodexBackup(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME)
+}
+
+export function installCodexDeveloperInstructions(configPath, toml) {
+  const existing = readTopLevelTomlBlock(toml, 'developer_instructions')
+  backupUserCodexDeveloperInstructions(configPath, existing)
+  return upsertTopLevelTomlBlock(toml, 'developer_instructions', formatManagedCodexDeveloperInstructions())
+}
+
+export function uninstallCodexDeveloperInstructions(configPath, toml) {
+  const existing = readTopLevelTomlBlock(toml, 'developer_instructions')
+  if (!existing.includes('HelloAGENTS')) return toml
+  let next = removeTopLevelTomlBlock(toml, 'developer_instructions')
+  const backupDeveloperInstructions = readCodexDeveloperInstructionsBackup(configPath)
+  next = ensureTopLevelTomlBlock(next, 'developer_instructions', backupDeveloperInstructions)
+  removeCodexDeveloperInstructionsBackup(configPath)
+  return next
+}