spec_driven_docs/services/
status.rs1use camino::{Utf8Path, Utf8PathBuf};
10use serde::Serialize;
11
12use crate::domain::manifest::DOCS_SCRATCH_VAR;
13use crate::domain::paths::{
14 self, ActivePaths, Paths, UserEnv, docs_scratch_location, recorded_paths, variable,
15};
16use crate::domain::profile::{DocsRoot, ProfileId};
17use crate::domain::version::CanonVersion;
18use crate::error::AppError;
19use crate::landing::classify::{Classification, Signals, classify};
20use crate::services::verifier;
21
22pub const SCHEMA: &str = "sdd.status/6";
32
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
35#[serde(rename_all = "kebab-case")]
36pub enum Alignment {
37 Aligned,
39 BinaryNewer,
41 InstanceNewer,
43}
44
45#[derive(Debug, Serialize)]
47pub struct StatusReport {
48 pub schema: &'static str,
50 pub classification: Option<Classification>,
56 pub invalid: Option<String>,
59 pub instance: bool,
61 pub profile: Option<ProfileId>,
63 pub docs_root: Option<DocsRoot>,
65 pub docs_scratch: Option<Utf8PathBuf>,
67 pub docs_scratch_env: Option<String>,
70 pub canon_version: Option<CanonVersion>,
72 pub binary_version: CanonVersion,
74 pub alignment: Option<Alignment>,
76 pub managed_drift: usize,
78 pub adopted_drift: usize,
80 pub failures: usize,
82 pub ok: Option<bool>,
84 pub legacy_state: Vec<LegacyState>,
90 pub migration: Option<String>,
95 pub paths: Paths,
101 #[serde(skip_serializing_if = "Option::is_none")]
104 pub pending: Option<crate::self_depend::status::Pending>,
105}
106
107fn proposals(target: &Utf8Path, env: &UserEnv) -> paths::Proposals {
109 paths::proposals(env, |relative| target.join(relative).is_dir())
110}
111
112fn derived_paths(target: &Utf8Path, env: &UserEnv) -> Paths {
114 Paths {
115 user: env.user_paths().map(|user| {
116 let legacy = env
117 .legacy_state_root()
118 .map(|root| root.join(crate::domain::paths::SKILL_RECEIPT_FILE));
119 user.with_skill_entries_while_a_receipt_exists(legacy.as_deref())
120 }),
121 active: None,
122 candidates: paths::candidates(),
123 proposals: proposals(target, env),
124 }
125}
126
127fn absent(target: &Utf8Path, classified: Classified) -> StatusReport {
128 let env = UserEnv::from_process();
129 StatusReport {
130 schema: SCHEMA,
131 classification: Some(classified.classification),
132 invalid: classified.invalid,
133 migration: classified.migration,
134 legacy_state: legacy_state(&env),
135 paths: derived_paths(target, &env),
136 instance: false,
137 profile: None,
138 docs_root: None,
139 docs_scratch: None,
140 docs_scratch_env: variable(DOCS_SCRATCH_VAR),
141 canon_version: None,
142 binary_version: CanonVersion::current(),
143 alignment: None,
144 managed_drift: 0,
145 adopted_drift: 0,
146 failures: 0,
147 ok: None,
148 pending: crate::self_depend::status::pending(target, &env),
149 }
150}
151
152pub fn status(target: &Utf8Path) -> Result<StatusReport, AppError> {
160 let manifest = match verifier::read_manifest(target) {
161 Ok(manifest) => manifest,
162 Err(AppError::ManifestMissing(_)) => return Ok(absent(target, classify_target(target)?)),
163 Err(error) => return Err(error),
164 };
165 let classified = classify_target(target)?;
166 let report = verifier::verify(target)?;
167 let binary = CanonVersion::current();
168 let alignment = match manifest.canon_version.cmp(&binary) {
169 std::cmp::Ordering::Equal => Alignment::Aligned,
170 std::cmp::Ordering::Less => Alignment::BinaryNewer,
171 std::cmp::Ordering::Greater => Alignment::InstanceNewer,
172 };
173 let env = UserEnv::from_process();
174 let mut resolved = derived_paths(target, &env);
175 resolved.active = Some(ActivePaths {
176 profile: manifest.profile,
177 destinations: recorded_paths(manifest.docs_root),
178 docs_scratch: docs_scratch_location(manifest.docs_scratch.as_deref(), &env),
179 });
180 Ok(StatusReport {
181 schema: SCHEMA,
182 classification: (alignment != Alignment::InstanceNewer)
183 .then_some(classified.classification),
184 invalid: classified.invalid,
185 migration: classified.migration,
186 legacy_state: legacy_state(&env),
187 paths: resolved,
188 instance: true,
189 profile: Some(manifest.profile),
190 docs_root: Some(manifest.docs_root),
191 docs_scratch: manifest.docs_scratch,
192 docs_scratch_env: variable(DOCS_SCRATCH_VAR),
193 canon_version: Some(manifest.canon_version),
194 binary_version: binary,
195 alignment: Some(alignment),
196 managed_drift: report.managed_drift,
197 adopted_drift: report.adopted_drift,
198 failures: report.failures,
199 ok: Some(report.failures == 0),
200 pending: crate::self_depend::status::pending(target, &env),
201 })
202}
203
204#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
206pub struct LegacyState {
207 pub path: Utf8PathBuf,
209 pub kind: &'static str,
211 pub active: bool,
215}
216
217const LEGACY_STATE: [(&str, &str); 3] = [
223 ("plans", "plan-store"),
224 ("backups", "transaction-backups"),
225 ("skills.journal", "skill-journal"),
226];
227
228const LEGACY_CACHE: (&str, &str) = ("bundles", "bundle-cache");
230
231fn legacy_state(env: &UserEnv) -> Vec<LegacyState> {
235 let mut found = Vec::new();
236 if let Some(state) = env.state_root() {
237 for (name, kind) in LEGACY_STATE {
238 let path = state.path.join(name);
239 if path.symlink_metadata().is_ok() {
240 let active = match kind {
241 "plan-store" => std::fs::read_dir(path.join("plans"))
244 .is_ok_and(|mut plans| plans.any(|plan| plan.is_ok())),
245 "skill-journal" => true,
247 _ => false,
248 };
249 found.push(LegacyState { path, kind, active });
250 }
251 }
252 }
253 if let Some(cache) = env.cache_root() {
254 let path = cache.path.join(LEGACY_CACHE.0);
255 if path.symlink_metadata().is_ok() {
256 found.push(LegacyState {
257 path,
258 kind: LEGACY_CACHE.1,
259 active: false,
260 });
261 }
262 }
263 found
264}
265
266#[derive(Debug, Clone, PartialEq, Eq)]
268pub struct Classified {
269 pub classification: Classification,
271 pub invalid: Option<String>,
273 pub migration: Option<String>,
275 pub beneath: Classification,
278}
279
280pub fn classify_target(target: &Utf8Path) -> Result<Classified, AppError> {
296 if !target.is_dir() {
297 return Ok(Classified {
298 classification: Classification::Setup,
299 invalid: None,
300 migration: None,
301 beneath: Classification::Setup,
302 });
303 }
304 let observation = crate::landing::observe::observe(target)?;
305 let invalid = match (&observation.invalid, &observation.installation) {
306 (Some(reason), _) => Some(reason.clone()),
307 (None, _) => crate::domain::instance_config::InstanceConfig::read(target)
311 .err()
312 .map(|error| error.to_string()),
313 };
314 let written =
315 observation.installation.is_none() && invalid.is_none() && observation.corpus.settled();
316 let verdict = if written {
320 Some(
321 crate::services::assess::corpus(target, crate::gates::paths::docs_scratch_variable())?
322 .verdict(),
323 )
324 } else {
325 None
326 };
327 let homed = verdict == Some(crate::services::assess::Classification::Brownfield);
328 let scattered = verdict == Some(crate::services::assess::Classification::NeedsDecision);
329 let classification = classify(Signals {
330 invalid: invalid.is_some(),
331 installed: observation.installation.is_some(),
332 at_destination: observation
334 .installation
335 .as_ref()
336 .is_some_and(|installed| installed.canon_version == CanonVersion::current()),
337 drifted: observation
338 .installation
339 .as_ref()
340 .is_some_and(crate::landing::observe::Installation::drifted),
341 settled: homed,
342 scattered,
343 });
344 let migration = if invalid.is_none() {
348 crate::domain::instance_config::InstanceConfig::read(target)
349 .ok()
350 .and_then(|declaration| declaration.migration)
351 } else {
352 None
353 };
354 Ok(Classified {
355 classification: if migration.is_some() {
356 Classification::Migration
357 } else {
358 classification
359 },
360 invalid,
361 migration,
362 beneath: classification,
363 })
364}