1use camino::{Utf8Path, Utf8PathBuf};
19use serde::Serialize;
20
21use crate::adapters::history::History;
22use crate::domain::instance_config::{
23 CONFIG_PATH, InstanceConfig, with_migration, without_migration,
24};
25use crate::domain::migration::{
26 Event, Kind, Marking, Placement, REGISTRY_FILE, REGISTRY_SCHEMA, Registry, SOURCES_DIR, Source,
27 Status, kind_of, slug_of,
28};
29use crate::domain::ownership::Sha256;
30use crate::error::AppError;
31use crate::landing::classify::Classification;
32
33pub const SCHEMA: &str = "sdd.migrate/1";
35
36pub const MIGRATIONS_DIR: &str = "migrations";
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
41#[serde(rename_all = "kebab-case")]
42pub enum Home {
43 Recognized,
45 Unrecognized,
47}
48
49#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
51pub struct Entry {
52 pub path: Utf8PathBuf,
54 pub kind: Kind,
56 pub sha256: String,
58 pub placement: Placement,
60 pub home: Home,
62}
63
64#[derive(Debug, Serialize)]
66pub struct Inventory {
67 pub schema: &'static str,
69 pub documents: Vec<Entry>,
71}
72
73#[derive(Debug, Serialize)]
75pub struct ArchiveReport {
76 pub schema: &'static str,
78 pub id: String,
80 pub workspace: Utf8PathBuf,
82 pub base_commit: String,
84 pub archived: Vec<Utf8PathBuf>,
86 pub in_place: Vec<Utf8PathBuf>,
88 pub applied: bool,
90}
91
92#[derive(Debug, Serialize)]
94pub struct SourceState {
95 pub id: String,
97 pub path: Utf8PathBuf,
99 pub status: Status,
101 pub group: Option<String>,
103 pub changed: bool,
106}
107
108#[derive(Debug, Serialize)]
110pub struct StatusReport {
111 pub schema: &'static str,
113 pub id: String,
115 pub workspace: Utf8PathBuf,
117 pub base_commit: String,
119 pub sources: Vec<SourceState>,
121 pub unfinished: Vec<String>,
123}
124
125#[derive(Debug, Serialize)]
127pub struct MarkReport {
128 pub schema: &'static str,
130 pub marked: Vec<String>,
132 pub status: Status,
134}
135
136#[derive(Debug, Serialize)]
138pub struct CloseReport {
139 pub schema: &'static str,
141 pub id: String,
143 pub workspace: Utf8PathBuf,
145 pub applied: bool,
147}
148
149pub fn inventory(target: &Utf8Path) -> Result<Inventory, AppError> {
157 let corpus =
158 crate::services::assess::corpus(target, crate::gates::paths::docs_scratch_variable())?;
159 let homes: Vec<String> = corpus
160 .doc_roots
161 .iter()
162 .chain(&corpus.methodology_markers)
163 .cloned()
164 .collect();
165 let mut documents = Vec::new();
166 for path in &corpus.documents {
167 let bytes = std::fs::read(target.join(path))?;
168 documents.push(entry(path, &bytes, &homes));
169 }
170 Ok(Inventory {
171 schema: SCHEMA,
172 documents,
173 })
174}
175
176fn entry(path: &Utf8Path, bytes: &[u8], homes: &[String]) -> Entry {
178 let metadata = crate::services::assess::is_root_metadata(path);
179 let kind = kind_of(path, metadata);
180 let recognized = metadata
181 || matches!(kind, Kind::Decision | Kind::Spec)
182 || homes.iter().any(|home| path.starts_with(home.as_str()));
183 Entry {
184 path: path.to_owned(),
185 kind,
186 sha256: Sha256::of(bytes).to_string(),
187 placement: if metadata {
188 Placement::InPlace
189 } else {
190 Placement::Archived
191 },
192 home: if recognized {
193 Home::Recognized
194 } else {
195 Home::Unrecognized
196 },
197 }
198}
199
200pub fn open_migration(target: &Utf8Path) -> Result<Option<String>, AppError> {
206 InstanceConfig::read(target)
207 .map(|declaration| declaration.migration)
208 .map_err(|error| AppError::Refused(error.to_string()))
209}
210
211pub fn workspace(target: &Utf8Path, id: &str) -> Result<Utf8PathBuf, AppError> {
218 let state = crate::domain::paths::UserEnv::from_process()
219 .state_root()
220 .ok_or_else(|| {
221 AppError::Refused(
222 "no state root resolves: set HOME or XDG_STATE_HOME so the archive has a home"
223 .to_string(),
224 )
225 })?;
226 Ok(state
227 .path
228 .join(MIGRATIONS_DIR)
229 .join(crate::stage::stage_name(target))
230 .join(id))
231}
232
233fn history(target: &Utf8Path) -> Result<History, AppError> {
235 History::open(target).map_err(|missing| {
236 AppError::Refused(format!(
237 "{missing}; a migration archives only what Git holds, so commit the corpus in a repository first (setup:an-archive-moves-only-committed-documents)"
238 ))
239 })
240}
241
242fn now() -> String {
244 jiff::Timestamp::now()
245 .strftime("%Y-%m-%dT%H:%M:%SZ")
246 .to_string()
247}
248
249pub fn archive(
262 target: &Utf8Path,
263 trunk: Option<&str>,
264 apply: bool,
265) -> Result<ArchiveReport, AppError> {
266 if let Some(id) = open_migration(target)? {
267 return Err(AppError::Refused(format!(
268 "the migration {id} is already open; read it with 'sdd migrate status'"
269 )));
270 }
271 let found = crate::services::status::classify_target(target)?.classification;
272 if found != Classification::Migration {
273 return Err(AppError::Refused(format!(
274 "sdd migrate archive serves a migration target, and this target is {found}"
275 )));
276 }
277 let history = history(target)?;
278 if history.head().is_none() {
279 return Err(AppError::Refused(
280 "the repository has no commit, so Git holds none of the corpus; commit it first"
281 .to_string(),
282 ));
283 }
284 let trunk = trunk
285 .map(str::to_string)
286 .or_else(|| history.default_trunk())
287 .ok_or_else(|| {
288 AppError::Refused(
289 "the remote's HEAD names no local branch; name the trunk with --trunk <ref>"
290 .to_string(),
291 )
292 })?;
293 let base_commit = history.commit_of(&trunk).ok_or_else(|| {
294 AppError::Refused(format!(
295 "the trunk {trunk} names no commit; name the trunk with --trunk <ref>"
296 ))
297 })?;
298 let listed = inventory(target)?.documents;
299 let paths: Vec<&Utf8Path> = listed.iter().map(|entry| entry.path.as_path()).collect();
300 let mut differing = history.differing(&base_commit, &paths)?;
303 differing.extend(
304 documents_at(target, &history, &base_commit)?
305 .into_iter()
306 .filter(|path| !paths.contains(&path.as_path())),
307 );
308 differing.sort();
309 if !differing.is_empty() {
310 let names: Vec<String> = differing.iter().map(ToString::to_string).collect();
311 return Err(AppError::Refused(format!(
312 "these documents differ from the trunk's copy on {trunk}: {}; integrate their edits onto the trunk, then run the archive again (setup:an-archive-moves-only-committed-documents)",
313 names.join(", ")
314 )));
315 }
316 for written in [CONFIG_PATH, crate::domain::manifest::MANIFEST_PATH] {
317 crate::adapters::fs::check_destination(target, Utf8Path::new(written)).map_err(
318 |refusal| {
319 AppError::Refused(format!(
320 "{written}: {refusal}; the archive writes nothing through it"
321 ))
322 },
323 )?;
324 }
325 let stamp = jiff::Timestamp::now()
326 .strftime("%Y%m%dT%H%M%SZ")
327 .to_string();
328 let planned = workspace(target, &stamp)?;
331 let workspace = match planned.parent() {
332 Some(runs) if apply => crate::adapters::fs::claim_run_dir(runs, &stamp)?,
333 _ => planned,
334 };
335 let id = workspace.file_name().unwrap_or(stamp.as_str()).to_string();
336 let (archived, in_place): (Vec<&Entry>, Vec<&Entry>) = listed
337 .iter()
338 .partition(|entry| entry.placement == Placement::Archived);
339 let report = ArchiveReport {
340 schema: SCHEMA,
341 id: id.clone(),
342 workspace: workspace.clone(),
343 base_commit: base_commit.clone(),
344 archived: archived.iter().map(|entry| entry.path.clone()).collect(),
345 in_place: in_place.iter().map(|entry| entry.path.clone()).collect(),
346 applied: apply,
347 };
348 if !apply {
349 return Ok(report);
350 }
351 for entry in &archived {
352 let bytes = std::fs::read(target.join(&entry.path))?;
353 let copy = workspace.join(SOURCES_DIR).join(&entry.path);
354 crate::adapters::fs::write_atomic(©, &bytes)?;
355 if Sha256::of(&std::fs::read(©)?).to_string() != entry.sha256 {
356 return Err(AppError::Refused(format!(
357 "{copy} does not read back as the bytes it was copied from; nothing was moved"
358 )));
359 }
360 }
361 let registry = new_registry(&id, &base_commit, &listed);
362 write_registry(&workspace, ®istry)?;
363 write_declaration(target, |text| with_migration(text, &id))?;
364 for entry in &archived {
365 crate::adapters::fs::remove_within(target, &entry.path)?;
366 prune_empty_parents(target, &entry.path);
367 }
368 Ok(report)
369}
370
371fn new_registry(id: &str, base_commit: &str, listed: &[Entry]) -> Registry {
377 let at = now();
378 let mut ordered: Vec<&Entry> = listed.iter().collect();
379 ordered.sort_by(|left, right| left.path.as_str().cmp(right.path.as_str()));
380 let mut sources: Vec<Source> = Vec::new();
381 for entry in ordered {
382 let mut slug = slug_of(&entry.path);
383 let mut suffix = 2;
384 while sources.iter().any(|source| source.id == slug) {
385 slug = format!("{}-{suffix}", slug_of(&entry.path));
386 suffix += 1;
387 }
388 sources.push(Source {
389 id: slug,
390 path: entry.path.clone(),
391 sha256: entry.sha256.clone(),
392 kind: entry.kind,
393 placement: entry.placement,
394 tags: Vec::new(),
395 group: None,
396 status: Status::Pending,
397 history: vec![Event {
398 at: at.clone(),
399 status: Status::Pending,
400 reason: None,
401 }],
402 });
403 }
404 Registry {
405 schema_version: REGISTRY_SCHEMA,
406 id: id.to_string(),
407 base_commit: base_commit.to_string(),
408 sources,
409 groups: Vec::new(),
410 }
411}
412
413fn write_declaration(target: &Utf8Path, change: impl Fn(&str) -> String) -> Result<(), AppError> {
416 let path = target.join(CONFIG_PATH);
417 let text = match std::fs::read_to_string(&path) {
418 Ok(text) => text,
419 Err(error) if error.kind() == std::io::ErrorKind::NotFound => String::new(),
420 Err(error) => return Err(AppError::Io(error)),
421 };
422 let changed = change(&text);
423 crate::adapters::fs::write_within(target, Utf8Path::new(CONFIG_PATH), changed.as_bytes())?;
424 rerecord_declaration(target, changed.as_bytes())
425}
426
427fn rerecord_declaration(target: &Utf8Path, bytes: &[u8]) -> Result<(), AppError> {
430 let manifest = target.join(crate::domain::manifest::MANIFEST_PATH);
431 let Ok(text) = std::fs::read_to_string(&manifest) else {
432 return Ok(());
433 };
434 let mut document: serde_json::Value = serde_json::from_str(&text)
435 .map_err(|error| AppError::ManifestInvalid(error.to_string()))?;
436 let recorded = document
437 .get("adopted_files")
438 .and_then(serde_json::Value::as_array)
439 .is_some_and(|entries| {
440 entries.iter().any(|entry| {
441 entry.get("destination").and_then(serde_json::Value::as_str) == Some(CONFIG_PATH)
442 })
443 });
444 if !recorded {
445 return Ok(());
446 }
447 crate::services::policy::with_adopted_record(
448 &mut document,
449 "",
450 Utf8Path::new(CONFIG_PATH),
451 bytes,
452 &[],
453 )?;
454 let rendered = serde_json::to_string_pretty(&document)
455 .map_err(|error| AppError::ManifestInvalid(error.to_string()))?;
456 crate::adapters::fs::write_within(
457 target,
458 Utf8Path::new(crate::domain::manifest::MANIFEST_PATH),
459 format!("{rendered}\n").as_bytes(),
460 )?;
461 Ok(())
462}
463
464fn prune_empty_parents(target: &Utf8Path, path: &Utf8Path) {
467 let mut parent = path.parent();
468 while let Some(directory) = parent.filter(|directory| !directory.as_str().is_empty()) {
469 if std::fs::remove_dir(target.join(directory)).is_err() {
470 break;
471 }
472 parent = directory.parent();
473 }
474}
475
476fn write_registry(workspace: &Utf8Path, registry: &Registry) -> Result<(), AppError> {
478 let text = registry
479 .render()
480 .map_err(|error| AppError::Refused(error.to_string()))?;
481 crate::adapters::fs::write_atomic(&workspace.join(REGISTRY_FILE), text.as_bytes())?;
482 Ok(())
483}
484
485fn opened(target: &Utf8Path) -> Result<(String, Utf8PathBuf, Registry), AppError> {
492 let id = open_migration(target)?.ok_or_else(|| {
493 AppError::Refused("no migration is open here; 'sdd migrate archive' opens one".to_string())
494 })?;
495 let workspace = workspace(target, &id)?;
496 let text = std::fs::read_to_string(workspace.join(REGISTRY_FILE)).map_err(|error| {
497 AppError::Refused(format!(
498 "the registry of {id} cannot be read under {workspace}: {error}; 'sdd migrate archive --rebuild --apply' recreates the archive from Git"
499 ))
500 })?;
501 let registry = Registry::parse(&text).map_err(|error| AppError::Refused(error.to_string()))?;
502 Ok((id, workspace, registry))
503}
504
505pub fn rebuild(target: &Utf8Path, apply: bool) -> Result<ArchiveReport, AppError> {
519 let id = open_migration(target)?.ok_or_else(|| {
520 AppError::Refused("no migration is open here, so there is nothing to rebuild".to_string())
521 })?;
522 let workspace = workspace(target, &id)?;
523 let history = history(target)?;
524 let registry = if let Ok(text) = std::fs::read_to_string(workspace.join(REGISTRY_FILE)) {
525 Registry::parse(&text).map_err(|error| AppError::Refused(error.to_string()))?
526 } else {
527 reconstructed(target, &history, &id)?
528 };
529 let archived: Vec<&Source> = registry
530 .sources
531 .iter()
532 .filter(|source| source.placement == Placement::Archived)
533 .collect();
534 let mut recreated = Vec::new();
535 for source in &archived {
536 let bytes = history
537 .show(®istry.base_commit, &source.path)
538 .ok_or_else(|| {
539 AppError::Refused(format!(
540 "{} holds no {}; fetch the history that holds it",
541 registry.base_commit, source.path
542 ))
543 })?;
544 if Sha256::of(&bytes).to_string() != source.sha256 {
545 return Err(AppError::Refused(format!(
546 "{} at {} does not match its registered checksum",
547 source.path, registry.base_commit
548 )));
549 }
550 recreated.push((source.path.clone(), bytes));
551 }
552 if apply {
553 for (path, bytes) in &recreated {
554 crate::adapters::fs::write_atomic(&workspace.join(SOURCES_DIR).join(path), bytes)?;
555 }
556 if !workspace.join(REGISTRY_FILE).is_file() {
557 write_registry(&workspace, ®istry)?;
558 }
559 }
560 Ok(ArchiveReport {
561 schema: SCHEMA,
562 id,
563 workspace,
564 base_commit: registry.base_commit.clone(),
565 archived: archived.iter().map(|source| source.path.clone()).collect(),
566 in_place: registry
567 .sources
568 .iter()
569 .filter(|source| source.placement == Placement::InPlace)
570 .map(|source| source.path.clone())
571 .collect(),
572 applied: apply,
573 })
574}
575
576fn documents_at(
579 target: &Utf8Path,
580 history: &History,
581 commit: &str,
582) -> Result<Vec<Utf8PathBuf>, AppError> {
583 let scratch = crate::services::assess::scratch_within(
584 target,
585 crate::gates::paths::docs_scratch_variable(),
586 );
587 Ok(history
588 .files_at(commit)?
589 .into_iter()
590 .filter(|path| {
591 crate::services::assess::is_document_path(path)
592 && !scratch
593 .as_ref()
594 .is_some_and(|scratch| path.starts_with(scratch))
595 })
596 .collect())
597}
598
599fn reconstructed(target: &Utf8Path, history: &History, id: &str) -> Result<Registry, AppError> {
607 let base = history
608 .before_adding(
609 Utf8Path::new(CONFIG_PATH),
610 &crate::domain::instance_config::migration_line(id),
611 )
612 .ok_or_else(|| {
613 AppError::Refused(format!(
614 "no commit records the migration {id} in {CONFIG_PATH}, so the base commit cannot be found"
615 ))
616 })?;
617 let mut listed = Vec::new();
618 for path in documents_at(target, history, &base)? {
619 if let Some(bytes) = history.show(&base, &path) {
620 listed.push(entry(&path, &bytes, &[]));
621 }
622 }
623 Ok(new_registry(id, &base, &listed))
624}
625
626pub fn mark(
636 target: &Utf8Path,
637 name: &str,
638 status: Status,
639 marking: &Marking,
640) -> Result<MarkReport, AppError> {
641 for destination in &marking.destinations {
644 let inside = !destination.as_str().is_empty()
645 && destination.components().all(|part| {
646 matches!(
647 part,
648 camino::Utf8Component::Normal(_) | camino::Utf8Component::CurDir
649 )
650 });
651 if !inside {
652 return Err(AppError::Usage(format!(
653 "the destination {destination} leaves the target; name a path relative to the target root"
654 )));
655 }
656 }
657 let (_, workspace, mut registry) = opened(target)?;
658 let marked = registry
659 .mark(name, status, marking, &now())
660 .map_err(|error| AppError::Refused(error.to_string()))?;
661 write_registry(&workspace, ®istry)?;
662 Ok(MarkReport {
663 schema: SCHEMA,
664 marked,
665 status,
666 })
667}
668
669pub fn status(target: &Utf8Path) -> Result<StatusReport, AppError> {
677 let (id, workspace, registry) = opened(target)?;
678 let sources = registry
679 .sources
680 .iter()
681 .map(|source| {
682 let held = match source.placement {
683 Placement::Archived => workspace.join(SOURCES_DIR).join(&source.path),
684 Placement::InPlace => target.join(&source.path),
685 };
686 let changed = match std::fs::read(&held) {
687 Ok(bytes) => Sha256::of(&bytes).to_string() != source.sha256,
688 Err(error) if error.kind() == std::io::ErrorKind::NotFound => true,
689 Err(error) => return Err(AppError::Io(error)),
690 };
691 Ok(SourceState {
692 id: source.id.clone(),
693 path: source.path.clone(),
694 status: source.status,
695 group: source.group.clone(),
696 changed,
697 })
698 })
699 .collect::<Result<Vec<_>, AppError>>()?;
700 let root = target.canonicalize_utf8()?;
701 Ok(StatusReport {
702 schema: SCHEMA,
703 id,
704 workspace,
705 base_commit: registry.base_commit.clone(),
706 sources,
707 unfinished: registry.unfinished(|path| holds(&root, target, path)),
708 })
709}
710
711fn holds(root: &Utf8Path, target: &Utf8Path, destination: &Utf8Path) -> bool {
714 target
715 .join(destination)
716 .canonicalize_utf8()
717 .is_ok_and(|held| held.starts_with(root) && held.is_file())
718}
719
720pub fn close(target: &Utf8Path, apply: bool) -> Result<CloseReport, AppError> {
730 let (id, workspace, registry) = opened(target)?;
731 let root = target.canonicalize_utf8()?;
732 let unfinished = registry.unfinished(|path| holds(&root, target, path));
733 if !unfinished.is_empty() {
734 return Err(AppError::Refused(format!(
735 "the migration {id} cannot close: {} (setup:close-refuses-an-unfinished-source)",
736 unfinished.join("; ")
737 )));
738 }
739 if apply {
740 write_declaration(target, without_migration)?;
741 }
742 Ok(CloseReport {
743 schema: SCHEMA,
744 id,
745 workspace,
746 applied: apply,
747 })
748}