CloudSeatbelt

Read-only Windows preflight for cloud-sync placeholders.

简体中文 · Research and differentiation · Specification

CloudSeatbelt answers a question that backup, migration, and sync tools often leave implicit: which files are actually safe on this disk right now? It scans Windows file metadata without opening file bodies, reports cloud-only and evictable files, compares snapshots for residency regressions, and generates a non-destructive action checklist.

It is a working CLI, not a dashboard shell. It does not authenticate to a provider, contact a cloud API, hydrate files, sync data, or create backups.

Why this exists

A cloud-sync folder can look complete in Explorer while some file bodies are not locally present. That matters before you unlink an account, reset a client, reinstall Windows, migrate a device, or trust a separate backup. CloudSeatbelt turns documented Windows attributes into reviewable JSON and Markdown evidence before the risky operation.

Quick start

Requirements: Windows 10/11 x86-64.

1. Download the Windows ZIP from the latest release.
2. Extract cloudseatbelt.exe.
3. Open PowerShell in that directory and run:

.\cloudseatbelt.exe scan 'C:\Users\you\OneDrive' `
  --json scan-before.json `
  --markdown scan-before.md `
  --fail-on-risk

Exit 2 means the scan completed and found cloud-only or evictable files. The reports are still valid; review them before proceeding. Exit 1 means the scan or report failed and must not be treated as complete.

Commands

cloudseatbelt scan <ROOT> --json <FILE> [--markdown <FILE>] [--fail-on-risk]
cloudseatbelt compare <BEFORE.json> <AFTER.json> [--json <FILE>] [--markdown <FILE>]
cloudseatbelt plan <SCAN.json> [--markdown <FILE>]

Scan

.\cloudseatbelt.exe scan 'C:\Users\you\OneDrive' `
  --json scan-before.json `
  --markdown scan-before.md

The snapshot includes sorted relative paths, logical and allocated bytes, raw Windows attributes, residency, risk, and stable reason codes. Links and junctions are recorded but never followed.

Compare

.\cloudseatbelt.exe compare scan-before.json scan-after.json `
  --json comparison.json `
  --markdown comparison.md

Exit 2 means at least one matched file regressed from safe local residency toward evictable or not-fully-local residency. Added and removed files are reported separately.

Plan

.\cloudseatbelt.exe plan scan-after.json --markdown local-residency-plan.md

The plan lists only files needing attention. It tells you to use the provider's supported Always keep on this device action, wait for transfers to finish, and rerun CloudSeatbelt. It never modifies attributes or invokes a provider.

Evidence model

Windows evidence	CloudSeatbelt status	Gate
OFFLINE, RECALL_ON_OPEN, or RECALL_ON_DATA_ACCESS	not_fully_local	High risk
PINNED	pinned_local	Safe
UNPINNED	evictable_local	Warning
None of the above	local	Safe

Recall evidence wins over pin intent when attributes conflict. Allocated size is informational; compression and sparse allocation mean that byte count alone cannot prove cloud residency.

The rules follow Microsoft's documentation for file attributes, Cloud Files placeholders, and allocated size.

Safety boundary

• Scan reads directory entries and metadata only; it never opens file bodies.
• The selected root cannot be a link or junction; child links are reported but not traversed.
• A traversal or metadata error fails immediately. No partial report is presented as trustworthy.
• Compare and plan read snapshots and write reports only.
• Input snapshots and output reports must use different paths, so evidence cannot be overwritten.
• There is no network code, provider authentication, repair command, telemetry, or background service.
• A clean report is local evidence for the scanned moment, not proof that a remote copy or backup exists.

Build from source

Install Rustup and Python 3.11 or newer, then:

git clone https://github.com/KanadeK/cloudseatbelt.git
cd cloudseatbelt
cargo build --release --locked
.\target\release\cloudseatbelt.exe --help

The repository selects the Windows GNU Rust toolchain and required format/lint components through rust-toolchain.toml.

Acceptance

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release --locked
python scripts/release_check.py

The final command also executes all three real CLI flows and creates the release ZIP in dist/. See Troubleshooting for exact failure-to-fix routes.

Project status

v0.1.0 is intentionally Windows-only and provider-neutral. The bounded prior-art search and rejected overlapping ideas are recorded in RESEARCH.md. Architectural tradeoffs are recorded in ADR-0001.

Contributing and security

See CONTRIBUTING.md for the narrow project scope and required gates. Report security problems privately as described in SECURITY.md.

Licensed under the MIT License.