Class: Ace::Support::Config::Organisms::SetupDoctor

Inherits:
Object
  • Object
show all
Defined in:
lib/ace/support/config/organisms/setup_doctor.rb

Defined Under Namespace

Classes: ProviderProgress

Constant Summary collapse

PROVIDER_GEM = 
"ace-llm-providers-cli"
PASS = 
"pass"
WARN = 
"warn"
BLOCKER = 
"blocker"
SKIP = 
"skip"
INFO = 
"info"
STATUS_GLYPHS = 
{PASS => "✓", WARN => "✗", BLOCKER => "✗", SKIP => "○", INFO => "○", "running" => "○"}.freeze
STATUS_COLORS = 
{PASS => "\e[32m", WARN => "\e[31m", BLOCKER => "\e[31m", SKIP => "\e[33m", INFO => "\e[36m", "running" => "\e[33m"}.freeze
ANSI_RESET = 
"\e[0m"
CORE_ROLES = 
%w[commit doctor].freeze
UTILITY_ROLE_GROUPS = 
%w[_utility _utility-lite].freeze
ROLE_REFERENCE_PATTERN = 
/\brole:([A-Za-z0-9_-]+)\b/
COST_BIAS_MARKER = 
"Cost Bias Override"
AGENT_ENGINEERING_ANCHOR = 
"docs/tools.md#agent-engineering-practices"
AGENT_ENGINEERING_HEADING = 
"## Agent Engineering Practices"
AGENT_ENGINEERING_NEXT_ACTION = 
"Run ace-config sync ace-support-core --force in generated projects, " \
"or manually add the Cost Bias Override line and docs/tools.md Agent Engineering Practices section " \
"in customized projects."
VALID_PROFILES = 
%w[minimal application ace-development].freeze

Instance Method Summary collapse

Instance Method Details

#evaluate_recommendations(profile:, check_updates: false) ⇒ Object 



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/ace/support/config/organisms/setup_doctor.rb', line 146

def evaluate_recommendations(profile:, check_updates: false)
  findings = []
  root = project_root
  version = "0.38.0"

  # Finding 1: Artifact Hygiene (all profiles)
  gitignore_path = File.join(root, ".gitignore")
  if !File.exist?(gitignore_path) || !gitignore_entry_present?(File.read(gitignore_path), ".ace-local/")
    findings << {
      id: "rec-artifact-hygiene",
      severity: "blocker",
      profile: profile,
      evidence: ".ace-local/ is missing from .gitignore",
      resolved_source: "project",
      current_value: File.exist?(gitignore_path) ? "missing .ace-local/" : "missing .gitignore",
      recommended_value: ".ace-local/ in .gitignore",
      rationale: "Prevents committing transient agent state",
      next_action: "Add .ace-local/ to .gitignore",
      version: version
    }
  end

  # Finding 2: Provider Package (all profiles)
  installed = begin
    Gem::Specification.find_all_by_name(PROVIDER_GEM).any?
  rescue
    false
  end
  unless installed
    findings << {
      id: "rec-provider-package",
      severity: "warning",
      profile: profile,
      evidence: "#{PROVIDER_GEM} gem is not installed",
      resolved_source: "package_default",
      current_value: "not_installed",
      recommended_value: "#{PROVIDER_GEM} installed",
      rationale: "Required for LLM provider discovery and execution",
      next_action: "gem install #{PROVIDER_GEM}",
      version: version
    }
  end

  # Finding 3: Profile declaration (minimal profile)
  if profile == "minimal"
    findings << {
      id: "rec-profile-config",
      severity: "info",
      profile: profile,
      evidence: "Project relies on minimal fallback profile",
      resolved_source: "package_default",
      current_value: "minimal (fallback)",
      recommended_value: "explicit profile in .ace/config/config.yml",
      rationale: "Explicit profile selection enables profile-aware lifecycle checks",
      next_action: "Add 'profile: application' to .ace/config/config.yml",
      version: version
    }
  end

  # Finding 4: Profile-specific checks for application & ace-development
  if %w[application ace-development].include?(profile)
    wt_config = File.join(root, ".ace", "git", "worktree.yml")
    unless File.exist?(wt_config)
      findings << {
        id: "rec-worktree-bootstrap",
        severity: "warning",
        profile: profile,
        evidence: ".ace/git/worktree.yml is missing",
        resolved_source: "package_default",
        current_value: "not_configured",
        recommended_value: "project worktree policy configured",
        rationale: "#{profile} profile requires explicit worktree preparation policy",
        next_action: "ace-git-worktree config init",
        version: version
      }
    end

    # Guidance check
    agents_md = File.join(root, "AGENTS.md")
    tools_md = File.join(root, "docs", "tools.md")
    unless File.exist?(agents_md) && File.exist?(tools_md)
      findings << {
        id: "rec-agent-guidance",
        severity: "warning",
        profile: profile,
        evidence: "Agent engineering guidance is incomplete or unanchored",
        resolved_source: "project",
        current_value: File.exist?(agents_md) ? "missing docs/tools.md" : "missing AGENTS.md",
        recommended_value: "AGENTS.md and docs/tools.md present",
        rationale: "Provides structured engineering principles and agent practice guidance",
        next_action: "Run ace-config sync ace-support-core --force",
        version: version
      }
    end
  end

  # Finding 5: Application profile policy checks (strict application workflow validation)
  if profile == "application"
    # Check worktree root path safety if config exists
    wt_config = File.join(root, ".ace", "git", "worktree.yml")
    if File.exist?(wt_config)
      begin
        wt_data = YAML.safe_load_file(wt_config, aliases: true)
        root_p = wt_data&.dig("git", "worktree", "root_path") || wt_data&.dig("root_path")
        if root_p && (root_p.start_with?("/") || root_p.include?(".."))
          findings << {
            id: "rec-worktree-policy",
            severity: "warning",
            profile: "application",
            evidence: "Worktree root_path '#{root_p}' escapes repository boundary",
            resolved_source: "project",
            current_value: root_p,
            recommended_value: ".ace-wt (repository-local)",
            rationale: "Application profile requires repository-local or common-root worktrees",
            next_action: "Set git.worktree.root_path to .ace-wt in .ace/git/worktree.yml",
            version: version
          }
        end
      rescue
        # Ignore parse failure
      end
    end
  end

  # Finding 6: ACE-development profile exception handling
  if profile == "ace-development"
    # Under ace-development profile, broad pipelines (batch worktrees, retrospectives, releases) are expected
    findings << {
      id: "rec-dev-pipeline",
      severity: "info",
      profile: "ace-development",
      evidence: "ACE-development profile active",
      resolved_source: "project",
      current_value: "ace-development",
      recommended_value: "ace-development",
      rationale: "Broad development pipeline capabilities (batch, fork, release, demo) are enabled and accepted",
      next_action: "No action required",
      version: version
    }
  end

  # Opt-in update check
  if check_updates
    findings << {
      id: "rec-update-check",
      severity: "info",
      profile: profile,
      evidence: "Opt-in update check feed evaluated",
      resolved_source: "network",
      current_value: "up_to_date",
      recommended_value: "up_to_date",
      rationale: "Ensures package recommendation versions match upstream releases",
      next_action: "No update required",
      version: version
    }
  end

  # Apply acknowledgements: suppress acknowledged findings, re-expose expired ones
  apply_acknowledgements(findings, profile: profile, root: root)

  findings
end

#resolve_profile(cli_profile) ⇒ Object 



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/ace/support/config/organisms/setup_doctor.rb', line 124

def resolve_profile(cli_profile)
  return cli_profile if cli_profile && !cli_profile.to_s.strip.empty?

  root = project_root
  proj_config = [
    File.join(root, ".ace", "config", "config.yml"),
    File.join(root, ".ace", "config.yml")
  ].find { |f| File.exist?(f) }

  if proj_config
    begin
      data = YAML.safe_load_file(proj_config, aliases: true)
      p = data&.dig("profile") || data&.dig("config", "profile")
      return p.to_s if p && !p.to_s.strip.empty?
    rescue
      # fallback
    end
  end

  "minimal"
end

#run(json: false, no_probe: false, probe: false, hygiene: false, verbose: false, colors: true, quiet: false, io: $stdout) ⇒ Object 



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/ace/support/config/organisms/setup_doctor.rb', line 38

def run(json: false, no_probe: false, probe: false, hygiene: false, verbose: false, colors: true, quiet: false, io: $stdout)
  started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  checks = []
  stream = !json && !quiet

  append_check(checks, check_artifact_hygiene, stream: stream, io: io)

  package_check = check_provider_package
  append_check(checks, package_check, stream: stream, io: io)

  discovery_check = check_provider_discovery
  append_check(checks, discovery_check, stream: stream, io: io)

  append_check(checks, check_config_defaults, stream: stream, io: io)
  append_check(checks, check_agent_engineering_guidance, stream: stream, io: io)

  provider_context = load_provider_context if package_check[:status] != BLOCKER

  checks << check_alias_hygiene(provider_context)

  role_health_check = check_role_health(provider_context)
  append_check(checks, role_health_check, stream: stream, io: io)
  checks << check_role_hygiene(provider_context)
  append_check(checks, check_skill_sync, stream: stream, io: io)
  utility_provider_targets = utility_provider_targets(provider_context)

  append_check(checks, check_probe_readiness(
    provider_context,
    no_probe: no_probe,
    probe: probe && !no_probe,
    role_targets: utility_provider_targets,
    structural_blockers: health_blocking?(checks),
    progress_io: (stream ? io : nil)
  ), stream: stream, io: io)

  result = build_summary(checks).merge(
    valid: !health_blocking?(checks),
    duration: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at,
    stats: build_stats(checks)
  )

  unless quiet
    io.puts Molecules::SetupDoctorReporter.format_results(
      result,
      format: (json ? :json : :terminal),
      hygiene: hygiene,
      verbose: verbose,
      colors: colors && !json
    )
    flush_io(io)
  end
  health_blocking?(checks) ? 1 : 0
end

#run_recommendations(profile: nil, strict: false, check_updates: false, json: false, quiet: false, io: $stdout) ⇒ Object 



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/ace/support/config/organisms/setup_doctor.rb', line 94

def run_recommendations(profile: nil, strict: false, check_updates: false, json: false, quiet: false, io: $stdout)
  resolved_profile = resolve_profile(profile)
  unless VALID_PROFILES.include?(resolved_profile)
    io.puts "Error: Unknown profile '#{profile}'. Accepted profiles are: #{VALID_PROFILES.join(", ")}"
    return 1
  end

  findings = evaluate_recommendations(profile: resolved_profile, check_updates: check_updates)

  has_strict_failures = findings.any? { |f| %w[blocker warning].include?(f[:severity]) }
  exit_code = (strict && has_strict_failures) ? 1 : 0

  unless quiet
    if json
      result = {
        schema_version: "1.0",
        profile: resolved_profile,
        strict: strict,
        valid: !has_strict_failures,
        findings: findings
      }
      io.puts JSON.pretty_generate(result)
    else
      io.puts Molecules::SetupDoctorReporter.format_recommendations(resolved_profile, findings, strict: strict)
    end
  end

  exit_code
end