helloagents 3.0.2-beta.1 → 3.0.7

package/scripts/plan-contract.mjs

@@ -0,0 +1,210 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, normalize } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveProjectPlanDir } from './project-storage.mjs'
+
+export const PLAN_CONTRACT_FILE_NAME = 'contract.json'
+const VALID_VERIFY_MODES = new Set(['test-first', 'review-first'])
+const VALID_ADVISOR_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 normalizeVerifyMode(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_VERIFY_MODES.has(normalized) ? normalized : ''
+}
+
+function normalizeUiStyleAdvisorContract(input = {}) {
+  return {
+    required: Boolean(input.required),
+    reason: typeof input.reason === 'string' ? input.reason.trim() : '',
+    focus: normalizeStringArray(input.focus),
+  }
+}
+
+function normalizeUiVisualValidationContract(input = {}) {
+  return {
+    required: Boolean(input.required),
+    reason: typeof input.reason === 'string' ? input.reason.trim() : '',
+    screens: normalizeStringArray(input.screens),
+    states: normalizeStringArray(input.states),
+  }
+}
+
+function normalizeUiContract(input = {}) {
+  const styleAdvisor = normalizeUiStyleAdvisorContract(input.styleAdvisor)
+  const visualValidation = normalizeUiVisualValidationContract(input.visualValidation)
+  const sourcePriority = normalizeStringArray(input.sourcePriority)
+  const designContract = Boolean(input.designContract)
+
+  return {
+    required: Boolean(input.required)
+      || designContract
+      || sourcePriority.length > 0
+      || styleAdvisor.required
+      || visualValidation.required,
+    designContract,
+    sourcePriority,
+    styleAdvisor,
+    visualValidation,
+  }
+}
+
+function normalizeAdvisorSources(values) {
+  return normalizeStringArray(values).filter((value) => VALID_ADVISOR_SOURCES.has(value))
+}
+
+function normalizeAdvisorContract(input = {}) {
+  return {
+    required: Boolean(input.required),
+    reason: typeof input.reason === 'string' ? input.reason.trim() : '',
+    focus: normalizeStringArray(input.focus),
+    preferredSources: normalizeAdvisorSources(input.preferredSources),
+  }
+}
+
+function resolvePlanDir(cwd, input = {}) {
+  const rawPlanDir = typeof input.planDir === 'string' ? input.planDir.trim() : ''
+  if (!rawPlanDir) return ''
+  return resolveProjectPlanDir(cwd, rawPlanDir)
+}
+
+export function getPlanContractPath(planDir) {
+  return join(planDir, PLAN_CONTRACT_FILE_NAME)
+}
+
+export function readPlanContract(planDir) {
+  try {
+    return JSON.parse(readFileSync(getPlanContractPath(planDir), 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+export function normalizePlanContract(input = {}) {
+  return {
+    version: 1,
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    verifyMode: normalizeVerifyMode(input.verifyMode),
+    reviewerFocus: normalizeStringArray(input.reviewerFocus),
+    testerFocus: normalizeStringArray(input.testerFocus),
+    ui: normalizeUiContract(input.ui),
+    advisor: normalizeAdvisorContract(input.advisor),
+  }
+}
+
+export function getAdvisorRequirement(contract = null) {
+  const normalized = normalizePlanContract(contract || {})
+  const advisor = normalized.advisor || normalizeAdvisorContract()
+  const styleAdvisor = normalized.ui?.styleAdvisor || normalizeUiStyleAdvisorContract()
+
+  return {
+    required: Boolean(advisor.required || styleAdvisor.required),
+    genericRequired: advisor.required,
+    styleRequired: styleAdvisor.required,
+    reason: [advisor.reason, styleAdvisor.reason].filter(Boolean).join('；'),
+    focus: normalizeStringArray([...advisor.focus, ...styleAdvisor.focus]),
+    preferredSources: advisor.preferredSources,
+  }
+}
+
+export function getVisualValidationRequirement(contract = null) {
+  const normalized = normalizePlanContract(contract || {})
+  return normalized.ui?.visualValidation || normalizeUiVisualValidationContract()
+}
+
+export function getPlanContractIssues(contract = null) {
+  if (!contract) {
+    return ['missing contract.json']
+  }
+
+  const normalized = normalizePlanContract(contract)
+  const advisorRequirement = getAdvisorRequirement(normalized)
+  const visualValidation = getVisualValidationRequirement(normalized)
+  const issues = []
+  if (!normalizeVerifyMode(normalized.verifyMode)) {
+    issues.push('contract.json missing valid verifyMode')
+  }
+  if (normalizeStringArray(normalized.testerFocus).length === 0) {
+    issues.push('contract.json missing testerFocus')
+  }
+  if (normalizeVerifyMode(normalized.verifyMode) === 'review-first' && normalizeStringArray(normalized.reviewerFocus).length === 0) {
+    issues.push('contract.json missing reviewerFocus for review-first flow')
+  }
+  if (normalized.ui?.required && normalizeStringArray(normalized.ui.sourcePriority).length === 0) {
+    issues.push('contract.json missing ui.sourcePriority')
+  }
+  if (normalized.ui?.styleAdvisor?.required && !String(normalized.ui.styleAdvisor.reason || '').trim()) {
+    issues.push('contract.json missing ui.styleAdvisor.reason')
+  }
+  if (normalized.ui?.styleAdvisor?.required && normalizeStringArray(normalized.ui.styleAdvisor.focus).length === 0) {
+    issues.push('contract.json missing ui.styleAdvisor.focus')
+  }
+  if (visualValidation.required && !String(visualValidation.reason || '').trim()) {
+    issues.push('contract.json missing ui.visualValidation.reason')
+  }
+  if (visualValidation.required && visualValidation.screens.length === 0 && visualValidation.states.length === 0) {
+    issues.push('contract.json missing ui.visualValidation.screens or ui.visualValidation.states')
+  }
+  if (advisorRequirement.genericRequired && !String(normalized.advisor.reason || '').trim()) {
+    issues.push('contract.json missing advisor.reason')
+  }
+  if (advisorRequirement.genericRequired && normalizeStringArray(normalized.advisor.focus).length === 0) {
+    issues.push('contract.json missing advisor.focus')
+  }
+  if (advisorRequirement.genericRequired && normalizeAdvisorSources(normalized.advisor.preferredSources).length === 0) {
+    issues.push('contract.json missing advisor.preferredSources')
+  }
+  return issues
+}
+
+export function writePlanContract(planDir, input = {}) {
+  mkdirSync(planDir, { recursive: true })
+  const payload = {
+    updatedAt: new Date().toISOString(),
+    ...normalizePlanContract(input),
+  }
+  writeFileSync(getPlanContractPath(planDir), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  return payload
+}
+
+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 planDir = resolvePlanDir(cwd, input)
+  if (!planDir) {
+    process.stdout.write(JSON.stringify({
+      suppressOutput: true,
+      error: 'planDir is required',
+    }))
+    return
+  }
+
+  const payload = writePlanContract(planDir, input)
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getPlanContractPath(planDir),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/project-storage.mjs

@@ -0,0 +1,235 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path'
+
+import { DEFAULTS } from './cli-config.mjs'
+
+export const PROJECT_DIR_NAME = '.helloagents'
+const PROJECTS_DIR_NAME = 'projects'
+const PROJECT_STORE_MODES = new Set(['local', 'repo-shared'])
+
+function safeJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+function runGitRevParse(cwd, args = []) {
+  try {
+    return execFileSync('git', ['rev-parse', ...args], {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 5_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
+function resolveGitTopLevel(cwd) {
+  const absolute = runGitRevParse(cwd, ['--path-format=absolute', '--show-toplevel'])
+  if (absolute) return normalize(absolute)
+
+  const raw = runGitRevParse(cwd, ['--show-toplevel'])
+  return raw ? normalize(resolve(cwd, raw)) : ''
+}
+
+function resolveGitCommonDir(cwd, repoRoot = '') {
+  const absolute = runGitRevParse(cwd, ['--path-format=absolute', '--git-common-dir'])
+  if (absolute) return normalize(absolute)
+
+  const raw = runGitRevParse(cwd, ['--git-common-dir'])
+  if (!raw) return ''
+  if (isAbsolute(raw)) return normalize(raw)
+  return normalize(resolve(repoRoot || cwd, raw))
+}
+
+function sanitizeRepoName(value = '') {
+  const normalized = String(value).trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+  return normalized || 'project'
+}
+
+function buildProjectKey(cwd) {
+  const repoRoot = resolveGitTopLevel(cwd)
+  const commonDir = resolveGitCommonDir(cwd, repoRoot)
+  const commonDirName = commonDir && basename(commonDir).toLowerCase() === '.git'
+    ? basename(dirname(commonDir))
+    : basename(commonDir || '')
+  const repoName = sanitizeRepoName(commonDirName || basename(repoRoot || cwd))
+  const keySource = commonDir || repoRoot || normalize(resolve(cwd))
+  const hash = createHash('sha1').update(keySource.toLowerCase()).digest('hex').slice(0, 12)
+
+  return {
+    repoName,
+    hash,
+    key: `${repoName}-${hash}`,
+    repoRoot,
+    commonDir,
+    keySource,
+  }
+}
+
+function normalizeStoreRelativePath(relativePath = '') {
+  return String(relativePath)
+    .replace(/[`'"]/g, '')
+    .trim()
+    .replace(/^\.helloagents[\\/]+/, '')
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+}
+
+function formatPromptPath(pathValue = '') {
+  return pathValue ? normalize(pathValue).replace(/\\/g, '/') : ''
+}
+
+export function normalizeProjectStoreMode(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return PROJECT_STORE_MODES.has(normalized) ? normalized : DEFAULTS.project_store_mode
+}
+
+export function getProjectConfigPath() {
+  return join(homedir(), PROJECT_DIR_NAME, 'helloagents.json')
+}
+
+export function getProjectStoreMode() {
+  const settings = safeJson(getProjectConfigPath()) || {}
+  return normalizeProjectStoreMode(settings.project_store_mode)
+}
+
+export function getProjectActivationDir(cwd) {
+  return join(cwd, PROJECT_DIR_NAME)
+}
+
+export function getProjectStatePath(cwd) {
+  return join(getProjectActivationDir(cwd), 'STATE.md')
+}
+
+export function isRepoSharedProjectStore(cwd) {
+  return getProjectStoreMode(cwd) === 'repo-shared'
+}
+
+export function getProjectStoreDir(cwd) {
+  if (!isRepoSharedProjectStore(cwd)) {
+    return getProjectActivationDir(cwd)
+  }
+
+  const projectKey = buildProjectKey(cwd)
+  return join(homedir(), PROJECT_DIR_NAME, PROJECTS_DIR_NAME, projectKey.key)
+}
+
+export function getProjectStoreSummary(cwd) {
+  const activationDir = getProjectActivationDir(cwd)
+  const storeDir = getProjectStoreDir(cwd)
+  const statePath = getProjectStatePath(cwd)
+  const projectKey = buildProjectKey(cwd)
+  const projectStoreMode = getProjectStoreMode(cwd)
+
+  return {
+    projectStoreMode,
+    activationDir,
+    storeDir,
+    statePath,
+    usesSharedStore: projectStoreMode === 'repo-shared',
+    projectKey: projectKey.key,
+    repoRoot: projectKey.repoRoot,
+    commonDir: projectKey.commonDir,
+    promptActivationDir: formatPromptPath(activationDir),
+    promptStoreDir: formatPromptPath(storeDir),
+    promptStatePath: formatPromptPath(statePath),
+  }
+}
+
+export function getProjectKnowledgeFilePath(cwd, fileName) {
+  return join(getProjectStoreDir(cwd), fileName)
+}
+
+export function getProjectDesignContractPath(cwd) {
+  return getProjectKnowledgeFilePath(cwd, 'DESIGN.md')
+}
+
+export function getProjectVerifyYamlPath(cwd) {
+  return getProjectKnowledgeFilePath(cwd, 'verify.yaml')
+}
+
+export function getProjectPlansDir(cwd) {
+  return join(getProjectStoreDir(cwd), 'plans')
+}
+
+export function resolveProjectPlanDir(cwd, rawPlanDir = '') {
+  const value = String(rawPlanDir).replace(/[`'"]/g, '').trim().replace(/[\\/]+$/, '')
+  if (!value) return ''
+
+  if (isAbsolute(value)) {
+    return normalize(value)
+  }
+
+  if (value.startsWith('.helloagents/')) {
+    return normalize(join(getProjectStoreDir(cwd), normalizeStoreRelativePath(value)))
+  }
+
+  if (value.startsWith('.helloagents\\')) {
+    return normalize(join(getProjectStoreDir(cwd), normalizeStoreRelativePath(value)))
+  }
+
+  if (value.startsWith('plans/')) {
+    return normalize(join(getProjectStoreDir(cwd), normalizeStoreRelativePath(value)))
+  }
+
+  if (value.startsWith('plans\\')) {
+    return normalize(join(getProjectStoreDir(cwd), normalizeStoreRelativePath(value)))
+  }
+
+  const fromCwd = normalize(join(cwd, value))
+  if (existsSync(fromCwd)) {
+    return fromCwd
+  }
+
+  return normalize(join(getProjectPlansDir(cwd), value))
+}
+
+export function describeProjectStoreFile(cwd, relativePath = '') {
+  const normalizedRelativePath = normalizeStoreRelativePath(relativePath)
+  const logicalPath = normalizedRelativePath ? `.helloagents/${normalizedRelativePath}` : '.helloagents/'
+  if (!isRepoSharedProjectStore(cwd)) {
+    return `\`${logicalPath}\``
+  }
+
+  const actualPath = formatPromptPath(join(getProjectStoreDir(cwd), normalizedRelativePath))
+  return `逻辑路径 \`${logicalPath}\`（实际存储：\`${actualPath}\`）`
+}
+
+export function buildProjectStorageHint(cwd) {
+  const summary = getProjectStoreSummary(cwd)
+  if (!summary.usesSharedStore) return ''
+  return `项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\`。`
+}
+
+export function buildProjectStorageBlock(cwd) {
+  const summary = getProjectStoreSummary(cwd)
+  if (!summary.usesSharedStore && !existsSync(summary.activationDir)) {
+    return ''
+  }
+
+  const details = {
+    project_store_mode: summary.projectStoreMode,
+    activation_dir: summary.promptActivationDir,
+    state_path: summary.promptStatePath,
+    knowledge_base_dir: summary.promptStoreDir,
+    uses_shared_store: summary.usesSharedStore,
+  }
+
+  return [
+    '## 当前项目存储',
+    '```json',
+    JSON.stringify(details, null, 2),
+    '```',
+    summary.usesSharedStore
+      ? '说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。'
+      : '说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。',
+  ].join('\n')
+}

package/scripts/ralph-loop.mjs

@@ -4,10 +4,11 @@
  * Runs on SubagentStop (Claude Code) and Stop (Codex CLI).
  * Auto-detects lint/test commands and blocks if they fail.
  */
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
+import { clearVerifyEvidence, detectCommands, hasUnsafeVerifyCommand, writeVerifyEvidence } from './verify-state.mjs';
 
 const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
 const CMD_TIMEOUT = 60_000; // 60s
@@ -25,60 +26,6 @@ function readSettings() {
   return {};
 }
 
-// ── Detect verification commands ──────────────────────────────────────
-function loadVerifyYaml(cwd) {
-  const f = join(cwd, '.helloagents', 'verify.yaml');
-  if (!existsSync(f)) return null;
-  try {
-    const content = readFileSync(f, 'utf-8');
-    const cmds = [];
-    let inCmds = false;
-    for (const line of content.split('\n')) {
-      const s = line.trim();
-      if (s.startsWith('commands:')) { inCmds = true; continue; }
-      if (inCmds) {
-        if (s.startsWith('- ') && !s.startsWith('# ')) {
-          const cmd = s.slice(2).trim().replace(/^["']|["']$/g, '');
-          if (cmd && !cmd.startsWith('#')) cmds.push(cmd);
-        } else if (s && !s.startsWith('#')) break;
-      }
-    }
-    return cmds.length ? cmds : null;
-  } catch { return null; }
-}
-
-function detectFromPackageJson(cwd) {
-  const f = join(cwd, 'package.json');
-  if (!existsSync(f)) return [];
-  try {
-    const scripts = JSON.parse(readFileSync(f, 'utf-8')).scripts || {};
-    return ['lint', 'typecheck', 'type-check', 'test', 'build']
-      .filter(k => k in scripts)
-      .map(k => `npm run ${k}`);
-  } catch { return []; }
-}
-
-function detectFromPyproject(cwd) {
-  const f = join(cwd, 'pyproject.toml');
-  if (!existsSync(f)) return [];
-  try {
-    const content = readFileSync(f, 'utf-8');
-    const cmds = [];
-    if (content.includes('[tool.ruff')) cmds.push('ruff check .');
-    if (content.includes('[tool.mypy')) cmds.push('mypy .');
-    if (content.includes('[tool.pytest')) cmds.push('pytest --tb=short -q');
-    return cmds;
-  } catch { return []; }
-}
-
-function detectCommands(cwd) {
-  const yaml = loadVerifyYaml(cwd);
-  if (yaml?.length) return yaml;
-  const pkg = detectFromPackageJson(cwd);
-  if (pkg.length) return pkg;
-  return detectFromPyproject(cwd);
-}
-
 // ── Circuit Breaker (consecutive failure tracking) ───────────────────
 const BREAKER_FILE_NAME = '.ralph-breaker.json';
 
@@ -123,12 +70,10 @@ function hasGitChanges(cwd) {
 }
 
 // ── Run verification ──────────────────────────────────────────────────
-const SHELL_OPERATORS = /[;&|`$(){}\n\r]/;
-
 function runVerify(commands, cwd) {
   const failures = [];
   for (const cmd of commands) {
-    if (SHELL_OPERATORS.test(cmd)) {
+    if (hasUnsafeVerifyCommand([cmd])) {
       failures.push({ cmd, output: 'Blocked: shell operators not allowed in verify commands' });
       continue;
     }
@@ -151,6 +96,11 @@ function runVerify(commands, cwd) {
 
 function handleSuccess(cwd, isSubagent) {
   resetBreaker(cwd);
+  writeVerifyEvidence(cwd, {
+    commands: detectCommands(cwd),
+    fastOnly: isSubagent,
+    source: isSubagent ? 'subagent' : 'stop',
+  });
 
   if (isSubagent) {
     process.stdout.write(JSON.stringify({
@@ -178,6 +128,7 @@ function handleSuccess(cwd, isSubagent) {
 }
 
 function handleFailure(failures, cwd) {
+  clearVerifyEvidence(cwd);
   const breaker = readBreaker(cwd);
   breaker.consecutive_failures += 1;
   breaker.last_failure = new Date().toISOString();