Add atomic stack fmt command

.github/workflows/ci.yaml

@@ -15,6 +15,19 @@ jobs:
     steps:
       - name: Check out repository
         uses: actions/checkout@v7
+      - name: Read supported specification revision
+        id: specification
+        shell: bash
+        run: |
+          grep -Eq '^[0-9a-f]{40}$' tests/specification-revision
+          revision=$(tr -d '\n' < tests/specification-revision)
+          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"
+      - name: Check out canonical specification
+        uses: actions/checkout@v7
+        with:
+          repository: stack-sh/specification
+          ref: ${{ steps.specification.outputs.revision }}
+          path: .stack-specification
       - name: Check whitespace
         run: git diff --check "$(git hash-object -t tree /dev/null)" HEAD
       - name: Install latest stable Rust toolchain
@@ -23,8 +36,12 @@ jobs:
         run: cargo +stable fmt --check
       - name: Run tests
         run: cargo +stable test --locked
+      - name: Run canonical formatter suite
+        env:
+          STACK_SPECIFICATION_DIR: ${{ github.workspace }}/.stack-specification
+        run: cargo +stable test --features conformance --test formatter-conformance --locked
       - name: Run Clippy
-        run: cargo +stable clippy --all-targets --locked -- -D warnings
+        run: cargo +stable clippy --all-targets --all-features --locked -- -D warnings
       - name: Build documentation
         env:
           RUSTDOCFLAGS: -D warnings
@@ -35,6 +52,8 @@ jobs:
           tool: cargo-llvm-cov@0.9.0
           fallback: none
       - name: Enforce test coverage
+        env:
+          STACK_SPECIFICATION_DIR: ${{ github.workspace }}/.stack-specification
         run: cargo +stable llvm-cov --all-features --locked --fail-under-lines 90 --fail-under-functions 95 --fail-under-regions 90
       - name: Build release binary
         run: cargo +stable build --release --locked
@@ -50,6 +69,7 @@ jobs:
           test -s Cargo.toml
           test -s Cargo.lock
           test -s src/main.rs
+          test -s tests/specification-revision
 
   msrv:
     name: Minimum supported Rust
@@ -62,4 +82,4 @@ jobs:
       - name: Run tests
         run: cargo +1.85.0 test --locked
       - name: Run Clippy
-        run: cargo +1.85.0 clippy --all-targets --locked -- -D warnings
+        run: cargo +1.85.0 clippy --all-targets --all-features --locked -- -D warnings

Cargo.toml

@@ -14,6 +14,14 @@ path = "src/main.rs"
 [dependencies]
 stack-engine = { git = "https://github.com/stack-sh/engine.git", rev = "07b71c783a3c1f9037d865b19672a9522eb0b24d" }
 
+[features]
+conformance = []
+
+[[test]]
+name = "formatter-conformance"
+path = "tests/formatter_conformance.rs"
+required-features = ["conformance"]
+
 [lints.clippy]
 expect_used = "deny"
 panic = "deny"

README.md

@@ -2,28 +2,31 @@
 
 `stack-sh/cli` is the private source repository for the native Rust `stack` command.
 
-The repository now contains the first native command: `stack check`. The CLI is not yet distributed as a supported external binary and its interface remains pre-release.
+The repository contains native validation and formatting commands. The CLI is not yet distributed as a supported external binary and its interface remains pre-release.
 
 ## Commands
 
 ```text
 stack check arch.stack
+stack fmt arch.stack
+stack fmt --check arch.stack
+stack fmt -
 ```
 
 `stack check` reads the file as bytes and runs the full compiler, theme, layout, and routing validation pipeline without changing the source. Diagnostics are written to standard error in source order. Standard output remains empty.
 
+`stack fmt` uses the engine formatter and preserves comments. File mode replaces changed source atomically through a temporary file in the same directory; unchanged files are not replaced. Syntax, encoding, and host I/O failures leave the original file untouched. `stack fmt -` reads bytes from standard input and writes only canonical source to standard output. `--check` never writes source and exits with status `1` when formatting is required.
+
 | Result | Exit status |
 | --- | ---: |
 | No error diagnostics, including warning-only input | `0` |
-| One or more Stack error diagnostics | `1` |
+| One or more Stack error diagnostics, or `fmt --check` finds a difference | `1` |
 | Invalid arguments, host I/O failure, or engine operational failure | `2` |
 
-The remaining planned commands are:
+The remaining planned command is:
 
 ```text
 stack render arch.stack -o arch.svg
-stack fmt arch.stack
-stack fmt --check arch.stack
 ```
 
 The CLI will link `stack-engine` as a native Rust dependency. It owns filesystem and standard-stream behavior, process exit codes, configuration discovery, and command presentation. It must not duplicate compiler, formatter, layout, or SVG-rendering logic.
@@ -37,11 +40,13 @@ The CLI requires Rust 1.85 or newer.
 ```sh
 cargo run -- check arch.stack
 cargo test --locked
-cargo clippy --all-targets --locked -- -D warnings
+cargo clippy --all-targets --all-features --locked -- -D warnings
 ```
 
 CI validates formatting, unit and process-level integration tests, at least 90% line/region coverage and 95% function coverage, Clippy, documentation, a release build, `--help`, and `--version` on stable Rust. Tests and Clippy also run on Rust 1.85.
 
+Canonical formatter behavior is checked against the pinned `stack-sh/specification` fixture revision recorded in `tests/specification-revision`.
+
 ## Licensing
 
 The private source code in this repository is not currently offered under an open-source license. See [LICENSING.md](./LICENSING.md) for the decisions required before external distribution.