CLI snapshot command + updated CI

Author: mdecimus

.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"752c70fd-8f83-4e36-a3c1-2848f12bcb75","pid":67212,"acquiredAt":1776432295230}

.github/workflows/release.yml

@@ -1,43 +1,7 @@
-# This file was autogenerated by dist: https://axodotdev.github.io/cargo-dist
-#
-# Copyright 2022-2024, axodotdev
-# SPDX-License-Identifier: MIT or Apache-2.0
-#
-# CI that:
-#
-# * checks for a Git Tag that looks like a release
-# * builds artifacts with dist (archives, installers, hashes)
-# * uploads those artifacts to temporary workflow zip
-# * on success, uploads the artifacts to a GitHub Release
-#
-# Note that the GitHub Release will be created with a generated
-# title/body based on your changelogs.
-
 name: Release
 permissions:
   "contents": "write"
 
-# This task will run whenever you push a git tag that looks like a version
-# like "1.0.0", "v0.1.0-prerelease.1", "my-app/0.1.0", "releases/v1.0.0", etc.
-# Various formats will be parsed into a VERSION and an optional PACKAGE_NAME, where
-# PACKAGE_NAME must be the name of a Cargo package in your workspace, and VERSION
-# must be a Cargo-style SemVer Version (must have at least major.minor.patch).
-#
-# If PACKAGE_NAME is specified, then the announcement will be for that
-# package (erroring out if it doesn't have the given version or isn't dist-able).
-#
-# If PACKAGE_NAME isn't specified, then the announcement will be for all
-# (dist-able) packages in the workspace with that version (this mode is
-# intended for workspaces with only one dist-able package, or with all dist-able
-# packages versioned/released in lockstep).
-#
-# If you push multiple tags at once, separate instances of this workflow will
-# spin up, creating an independent announcement for each one. However, GitHub
-# will hard limit this to 3 tags per commit, as it will assume more tags is a
-# mistake.
-#
-# If there's a prerelease-style suffix to the version, then the release(s)
-# will be marked as a prerelease.
 on:
   pull_request:
   push:
@@ -61,57 +25,39 @@ jobs:
           persist-credentials: false
           submodules: recursive
       - name: Install dist
-        # we specify bash to get pipefail; it guards against the `curl` command
-        # failing. otherwise `sh` won't catch that `curl` returned non-0
         shell: bash
         run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.31.0/cargo-dist-installer.sh | sh"
       - name: Cache dist
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/dist
-      # sure would be cool if github gave us proper conditionals...
-      # so here's a doubly-nested ternary-via-truthiness to try to provide the best possible
-      # functionality based on whether this is a pull_request, and whether it's from a fork.
-      # (PRs run on the *source* but secrets are usually on the *target* -- that's *good*
-      # but also really annoying to build CI around when it needs secrets to work right.)
       - id: plan
         run: |
           dist ${{ (!github.event.pull_request && format('host --steps=create --tag={0}', github.ref_name)) || 'plan' }} --output-format=json > plan-dist-manifest.json
           echo "dist ran successfully"
           cat plan-dist-manifest.json
           echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT"
       - name: "Upload dist-manifest.json"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: artifacts-plan-dist-manifest
           path: plan-dist-manifest.json
 
-  # Build and packages all the platform-specific things
   build-local-artifacts:
     name: build-local-artifacts (${{ join(matrix.targets, ', ') }})
-    # Let the initial task tell us to not run (currently very blunt)
     needs:
       - plan
     if: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix.include != null && (needs.plan.outputs.publishing == 'true' || fromJson(needs.plan.outputs.val).ci.github.pr_run_mode == 'upload') }}
     strategy:
       fail-fast: false
-      # Target platforms/runners are computed by dist in create-release.
-      # Each member of the matrix has the following arguments:
-      #
-      # - runner: the github runner
-      # - dist-args: cli flags to pass to dist
-      # - install-dist: expression to run to install dist on the runner
-      #
-      # Typically there will be:
-      # - 1 "global" task that builds universal installers
-      # - N "local" tasks that build each platform's binaries and platform-specific installers
       matrix: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix }}
     runs-on: ${{ matrix.runner }}
     container: ${{ matrix.container && matrix.container.image || null }}
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       BUILD_MANIFEST_NAME: target/distrib/${{ join(matrix.targets, '-') }}-dist-manifest.json
+      AWS_LC_SYS_PREBUILT_NASM: 1
     permissions:
       "attestations": "write"
       "contents": "read"
@@ -133,9 +79,8 @@ jobs:
           fi
       - name: Install dist
         run: ${{ matrix.install_dist.run }}
-      # Get the dist-manifest
       - name: Fetch local artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -149,14 +94,11 @@ jobs:
           dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json
           echo "dist ran successfully"
       - name: Attest
-        uses: actions/attest-build-provenance@v3
+        uses: actions/attest-build-provenance@v4
         with:
           subject-path: "target/distrib/*${{ join(matrix.targets, ', ') }}*"
       - id: cargo-dist
         name: Post-build
-        # We force bash here just because github makes it really hard to get values up
-        # to "real" actions without writing to env-vars, and writing to env-vars has
-        # inconsistent syntax between shell and powershell.
         shell: bash
         run: |
           # Parse out what we just built and upload it to scratch storage
@@ -166,14 +108,13 @@ jobs:
 
           cp dist-manifest.json "$BUILD_MANIFEST_NAME"
       - name: "Upload artifacts"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: artifacts-build-local-${{ join(matrix.targets, '_') }}
           path: |
             ${{ steps.cargo-dist.outputs.paths }}
             ${{ env.BUILD_MANIFEST_NAME }}
 
-  # Build and package all the platform-agnostic(ish) things
   build-global-artifacts:
     needs:
       - plan
@@ -188,14 +129,13 @@ jobs:
           persist-credentials: false
           submodules: recursive
       - name: Install cached dist
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/
       - run: chmod +x ~/.cargo/bin/dist
-      # Get all the local artifacts for the global tasks to use (for e.g. checksums)
       - name: Fetch local artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -213,7 +153,7 @@ jobs:
 
           cp dist-manifest.json "$BUILD_MANIFEST_NAME"
       - name: "Upload artifacts"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: artifacts-build-global
           path: |
@@ -242,7 +182,7 @@ jobs:
             name: arm-musl
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Build
         uses: houseabsolute/actions-rust-cross@v1
@@ -266,14 +206,12 @@ jobs:
         with:
           files: target/${{ matrix.target }}/release/stalwart-cli-${{ matrix.name }}.tar.gz
 
-  # Determines if we should publish/announce
   host:
     needs:
       - plan
       - build-local-artifacts
       - build-global-artifacts
       - extra-targets
-    # Only run if we're "publishing", and only if plan, local and global didn't fail (skipped is fine)
     if: ${{ always() && needs.plan.result == 'success' && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }}
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -286,14 +224,13 @@ jobs:
           persist-credentials: false
           submodules: recursive
       - name: Install cached dist
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/
       - run: chmod +x ~/.cargo/bin/dist
-      # Fetch artifacts from scratch-storage
       - name: Fetch artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -306,14 +243,12 @@ jobs:
           cat dist-manifest.json
           echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT"
       - name: "Upload dist-manifest.json"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
-          # Overwrite the previous copy
           name: artifacts-dist-manifest
           path: dist-manifest.json
-      # Create a GitHub Release while uploading all files to it
       - name: "Download GitHub Artifacts"
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: artifacts
@@ -351,15 +286,12 @@ jobs:
           persist-credentials: true
           repository: "stalwartlabs/homebrew-tap"
           token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
-      # So we have access to the formula
       - name: Fetch homebrew formulae
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: Formula/
           merge-multiple: true
-      # This is extra complex because you can make your Formula name not match your app name
-      # so we need to find releases with a *.rb file, and publish with that filename.
       - name: Commit formula files
         run: |
           git config --global user.name "${GITHUB_USER}"
@@ -385,9 +317,6 @@ jobs:
       - plan
       - host
       - publish-homebrew-formula
-    # use "always() && ..." to allow us to wait for all publish jobs while
-    # still allowing individual publish jobs to skip themselves (for prereleases).
-    # "host" however must run to completion, no skipping allowed!
     if: ${{ always() && needs.host.result == 'success' && (needs.publish-homebrew-formula.result == 'skipped' || needs.publish-homebrew-formula.result == 'success') }}
     runs-on: "ubuntu-22.04"
     env:

README.md

@@ -41,6 +41,7 @@ The tool fetches the server's schema on first use and derives every command, val
 | `get` / `query` | Fetch a single object or list / filter many. |
 | `create` / `update` / `delete` | Single-object mutations. |
 | `apply` | Apply a JSON plan of bulk creates, updates, and destroys (intended for Ansible, Terraform, NixOS, Pulumi, and CI/CD pipelines). |
+| `snapshot` | Export live server state as an `apply`-ready JSON plan. Useful for backups, cross-environment promotion, and round-trip disaster-recovery rehearsals. |
 
 Output is human-friendly by default (sectioned, with color when stdout is a TTY) and switches to compact JSON or NDJSON for machine consumption.
 
@@ -81,6 +82,8 @@ stalwart-cli create domain --field name=example.com --field isEnabled=true
 stalwart-cli update domain <id> --field description='Primary'
 stalwart-cli delete domain --ids <id>
 stalwart-cli apply --file plan.json         # bulk apply
+stalwart-cli snapshot Tenant Domain \        # export state as an apply plan
+    --output backup.json
 ```
 
 ## Documentation

src/cli/mod.rs

@@ -70,6 +70,8 @@ pub enum Command {
     Describe(DescribeArgs),
     /// Apply a bulk plan of creates, updates, and destroys from a JSON file
     Apply(ApplyArgs),
+    /// Snapshot one or more object types into a plan file consumable by `apply`
+    Snapshot(SnapshotArgs),
 }
 
 #[derive(Args, Debug)]
@@ -187,3 +189,34 @@ pub struct ApplyArgs {
     #[arg(long)]
     pub progress: bool,
 }
+
+#[derive(Args, Debug)]
+pub struct SnapshotArgs {
+    /// Object types to include (positional, at least one). Use bare object
+    /// names (`Domain`, `Account`, ...). For multi-variant types, all variants
+    /// are included. View / variant slash forms are rejected.
+    #[arg(required = true, value_name = "OBJECT")]
+    pub objects: Vec<String>,
+
+    /// Write the plan to this path instead of stdout
+    #[arg(long, value_name = "PATH")]
+    pub output: Option<PathBuf>,
+
+    /// Skip the destroy block at the top of the plan
+    #[arg(long)]
+    pub no_destroys: bool,
+
+    /// Include secret field values as returned by the server (default: strip)
+    #[arg(long)]
+    pub include_secrets: bool,
+
+    /// Comma-separated types whose references may be left unresolved. Any
+    /// reference to one of these types found in the data is dropped from the
+    /// exported plan.
+    #[arg(long, value_name = "TYPES", value_delimiter = ',')]
+    pub allow_unresolved: Vec<String>,
+
+    /// Suppress progress output on stderr
+    #[arg(long)]
+    pub quiet: bool,
+}

src/commands/apply.rs

@@ -336,7 +336,6 @@ impl Summary {
     }
 }
 
-/// Collect all `#id` references in a value tree (string values and object keys).
 fn collect_refs(value: &Value, out: &mut HashSet<String>) {
     match value {
         Value::String(s) => {
@@ -365,9 +364,6 @@ fn collect_refs(value: &Value, out: &mut HashSet<String>) {
     }
 }
 
-/// Build a per-request `createdIds` map: the subset of known created ids
-/// referenced by this request. Excludes ids being created in this very request
-/// (those resolve locally within the JMAP `create` context).
 fn request_created_ids(
     refs: &HashSet<String>,
     state_ids: &HashMap<String, String>,

src/commands/mod.rs

@@ -10,6 +10,7 @@ pub mod delete;
 pub mod describe;
 pub mod get;
 pub mod query;
+pub mod snapshot;
 pub mod update;
 
 use crate::app::context::Context;
@@ -25,5 +26,6 @@ pub fn dispatch(ctx: Context, cmd: Command) -> CliResult<()> {
         Command::Update(args) => update::run(&ctx, &args),
         Command::Delete(args) => delete::run(&ctx, &args),
         Command::Apply(args) => apply::run(&ctx, &args),
+        Command::Snapshot(args) => snapshot::run(&ctx, &args),
     }
 }