acumatica-cli 0.12.1__tar.gz → 0.13.1__tar.gz

{acumatica_cli-0.12.1 → acumatica_cli-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.12.1
+Version: 0.13.1
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -38,27 +38,23 @@ Acumatica configuration normally lives in the web UI: wizards, screens, and manu
 uv tool install acumatica-cli
 
 acu config init --host erp.example.com my-erp
-cd my-erp                                # edit .env: set ACU_PASSWORD
+cd my-erp                                # edit .env: set ACU_PASSWORD, ACU_TENANT
                                          # keep ACU_API_VERSION in sync with target.yaml
+                                         # start from a brand-new empty tenant
 
 acu config check                         # read-only preflight (incl. target.yaml)
 acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
-acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/ (, master/)
-acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
+# or hosted: acu --tenant DEV bootstrap
+acu --tenant DEV apply config/           # seed config/{bootstrap,baseline,setup,master}/
+acu --tenant DEV run scenario/           # once capital → buy → build → sell
+acu --tenant DEV diff config/            # prove zero drift (exit 2 on drift)
+acu --tenant DEV snapshot                # capture state/ trial-balance
+# warm: capital once-skips; Owner Capital stays 50000 (not 100000)
+acu --tenant DEV run scenario/
 ```
 
-**Distribution demo seed** (inventory, warehouse, items, vendors/customers, lifecycle scenarios):
-
-```sh
-acu config init --flavor distribution --host erp.example.com my-dist
-cd my-dist                               # edit .env; start from an empty tenant
-acu config check && acu bootstrap \
-  && acu apply config/ && acu run scenario/ && acu diff config/
-# warm re-run: capital once-skips; Owner Capital stays 50000 (not 100000)
-acu run scenario/
-```
-
-See [docs/distribution.md](docs/distribution.md) for the entity map, once-guard, and apply-order notes.
+Bare `apply` / `diff` (no path args) also prefer `config/` when those trees exist.
+See [docs/demo-seed.md](docs/demo-seed.md) for the entity map, once-guard, and apply-order notes.
 
 **Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
 
@@ -67,8 +63,8 @@ acu config init --host customer.acumatica.com my-erp
 cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; ACU_SSH=
 acu config check                         # REST preflight; ssh probe is skipped
 acu --tenant DEV bootstrap               # publish AcuBootstrap via REST only
-acu --tenant DEV apply
-acu --tenant DEV diff
+acu --tenant DEV apply config/
+acu --tenant DEV diff config/
 # offline UI fallback when REST publish is blocked:
 acu bootstrap --export AcuBootstrap.zip  # import + publish on SM204505
 ```
@@ -89,13 +85,14 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
+├── snapshot [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
+│                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     dump live tenant state as seed YAML (inverse of apply)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
-    ├── init [--host HOST] [--flavor distribution] [DIR]
-    │                                 scaffold a data repo (.env, target.yaml, example YAML)
+    ├── init [--host HOST] [DIR]      scaffold full data repo (config/, scenario/, target.yaml)
     ├── show                          print the resolved config as a complete .env
     └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
@@ -103,25 +100,29 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 `apply` and `diff` without FILES prefer `config/<name>/` when any seed child exists under `config/`; otherwise root `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
 A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
+`snapshot` without FILES defaults to `config/snapshot/`; writes go to `state/` (`--out`).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
 ## The data repo
 
 Your configuration lives in its own git repo.
-`acu config init` scaffolds finance-minimal seeds at the **root** (Bootstrap `project.xml` at `Bootstrap/1.0.0`, no `master/`, no scenario).
-`acu config init --flavor distribution` scaffolds the full demo under `config/` (same contract identity, expanded COA, masters) plus lifecycle `scenario/` and README.
+`acu config init` scaffolds a **single full seed** under `config/` (Bootstrap `project.xml` at `Bootstrap/1.0.0`, expanded COA, masters) plus lifecycle `scenario/`, observer `config/snapshot/`, and README. There is no `--flavor`.
 
 | Path | What it holds |
 | ---- | ------------- |
-| `bootstrap/` / `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
-| `baseline/` / `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs |
-| `setup/` / `config/setup/` | one-time actions: financial year, master calendar, open periods |
-| `config/master/` | distribution masters (prefs, warehouse, items, parties); flavor only |
-| `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build stub, sell |
+| `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
+| `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs, packaging |
+| `config/setup/` | one-time actions: financial year, master calendar, open periods |
+| `config/master/` | inventory/distribution masters (prefs, warehouse, items, parties) |
+| `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
+| `config/snapshot/` | observer views for `acu snapshot` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
+| `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
 | `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
 | `.env` | where to apply and who signs in, every key an `ACU_*` variable |
 
+Legacy data repos may still keep root `bootstrap/`…`master/`; bare `apply`/`diff` prefer `config/` when present and never merge both trees.
+
 Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order.
 The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
@@ -131,6 +132,10 @@ Scenario YAML is different — it describes transactions that flow forward.
 `acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
 `once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 
+`acu snapshot` is the third observation path: it captures live derived state (balances) into `state/` for git review. It is not `extract` (config seed) and not `diff` (desired vs actual config). Packaged golden is trial-balance via contract `inquire:` (`EndingBalance` fixed-point); inventory-summary is not golden this pass. `gi:` stays optional when a GI is V12-verified and **Expose via OData** is on (`params` fail-closed vs `$metadata`). After a cold `acu run scenario/ && acu snapshot`, warm `acu run scenario/10-seed-capital.yaml && acu snapshot --assert-unchanged` is the once-class gate (full scenario re-run is additive and moves cash observations on the TB).
+
+**Migration (path hard-cut):** bare defaults are `config/snapshot/` (views) and `state/` (observations). Root `snapshot/` and `snapshots/` are no longer defaulted — move files or pass explicit path args.
+
 ### Seed `endpoint:` symbols
 
 Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.
@@ -297,11 +302,13 @@ Configuration is one file: a decrypted `.env` at the repo root names the instanc
 
 The tier is self-contained.
 Each run scaffolds a synthetic single-org company from the packaged `acu config init` templates into a temporary directory, copies the real `.env` into it, and runs the installed `acu` binary from there — no data repo, no pre-existing fixtures on the instance.
-Scratch tenants (`E2E`, `E2EA`, `E2EB`) are created on the way in and always deleted on the way out, so nothing persists.
+Scratch tenants (`E2E`, `E2EA`, `E2EB`, `E2ESCEN`) are created on the way in and always deleted on the way out, so nothing persists.
+The packaged full `config init` seed (under `config/`) is the only scaffold.
 
 ```sh
 gmake e2e                                # whole tier, about 20 minutes
-gmake e2e FILE=test_provision_lifecycle  # one file, by stem or path
+gmake e2e FILE=test_provision_lifecycle  # apply/diff focus
+gmake e2e FILE=test_scenario_lifecycle   # scenario + snapshot focus
 ```
 
 ## License

{acumatica_cli-0.12.1 → acumatica_cli-0.13.1}/README.md

@@ -20,27 +20,23 @@ Acumatica configuration normally lives in the web UI: wizards, screens, and manu
 uv tool install acumatica-cli
 
 acu config init --host erp.example.com my-erp
-cd my-erp                                # edit .env: set ACU_PASSWORD
+cd my-erp                                # edit .env: set ACU_PASSWORD, ACU_TENANT
                                          # keep ACU_API_VERSION in sync with target.yaml
+                                         # start from a brand-new empty tenant
 
 acu config check                         # read-only preflight (incl. target.yaml)
 acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
-acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/ (, master/)
-acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
+# or hosted: acu --tenant DEV bootstrap
+acu --tenant DEV apply config/           # seed config/{bootstrap,baseline,setup,master}/
+acu --tenant DEV run scenario/           # once capital → buy → build → sell
+acu --tenant DEV diff config/            # prove zero drift (exit 2 on drift)
+acu --tenant DEV snapshot                # capture state/ trial-balance
+# warm: capital once-skips; Owner Capital stays 50000 (not 100000)
+acu --tenant DEV run scenario/
 ```
 
-**Distribution demo seed** (inventory, warehouse, items, vendors/customers, lifecycle scenarios):
-
-```sh
-acu config init --flavor distribution --host erp.example.com my-dist
-cd my-dist                               # edit .env; start from an empty tenant
-acu config check && acu bootstrap \
-  && acu apply config/ && acu run scenario/ && acu diff config/
-# warm re-run: capital once-skips; Owner Capital stays 50000 (not 100000)
-acu run scenario/
-```
-
-See [docs/distribution.md](docs/distribution.md) for the entity map, once-guard, and apply-order notes.
+Bare `apply` / `diff` (no path args) also prefer `config/` when those trees exist.
+See [docs/demo-seed.md](docs/demo-seed.md) for the entity map, once-guard, and apply-order notes.
 
 **Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
 
@@ -49,8 +45,8 @@ acu config init --host customer.acumatica.com my-erp
 cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; ACU_SSH=
 acu config check                         # REST preflight; ssh probe is skipped
 acu --tenant DEV bootstrap               # publish AcuBootstrap via REST only
-acu --tenant DEV apply
-acu --tenant DEV diff
+acu --tenant DEV apply config/
+acu --tenant DEV diff config/
 # offline UI fallback when REST publish is blocked:
 acu bootstrap --export AcuBootstrap.zip  # import + publish on SM204505
 ```
@@ -71,13 +67,14 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
+├── snapshot [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
+│                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     dump live tenant state as seed YAML (inverse of apply)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
-    ├── init [--host HOST] [--flavor distribution] [DIR]
-    │                                 scaffold a data repo (.env, target.yaml, example YAML)
+    ├── init [--host HOST] [DIR]      scaffold full data repo (config/, scenario/, target.yaml)
     ├── show                          print the resolved config as a complete .env
     └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
@@ -85,25 +82,29 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 `apply` and `diff` without FILES prefer `config/<name>/` when any seed child exists under `config/`; otherwise root `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
 A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
+`snapshot` without FILES defaults to `config/snapshot/`; writes go to `state/` (`--out`).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
 ## The data repo
 
 Your configuration lives in its own git repo.
-`acu config init` scaffolds finance-minimal seeds at the **root** (Bootstrap `project.xml` at `Bootstrap/1.0.0`, no `master/`, no scenario).
-`acu config init --flavor distribution` scaffolds the full demo under `config/` (same contract identity, expanded COA, masters) plus lifecycle `scenario/` and README.
+`acu config init` scaffolds a **single full seed** under `config/` (Bootstrap `project.xml` at `Bootstrap/1.0.0`, expanded COA, masters) plus lifecycle `scenario/`, observer `config/snapshot/`, and README. There is no `--flavor`.
 
 | Path | What it holds |
 | ---- | ------------- |
-| `bootstrap/` / `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
-| `baseline/` / `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs |
-| `setup/` / `config/setup/` | one-time actions: financial year, master calendar, open periods |
-| `config/master/` | distribution masters (prefs, warehouse, items, parties); flavor only |
-| `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build stub, sell |
+| `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
+| `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs, packaging |
+| `config/setup/` | one-time actions: financial year, master calendar, open periods |
+| `config/master/` | inventory/distribution masters (prefs, warehouse, items, parties) |
+| `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
+| `config/snapshot/` | observer views for `acu snapshot` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
+| `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
 | `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
 | `.env` | where to apply and who signs in, every key an `ACU_*` variable |
 
+Legacy data repos may still keep root `bootstrap/`…`master/`; bare `apply`/`diff` prefer `config/` when present and never merge both trees.
+
 Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order.
 The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
@@ -113,6 +114,10 @@ Scenario YAML is different — it describes transactions that flow forward.
 `acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
 `once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 
+`acu snapshot` is the third observation path: it captures live derived state (balances) into `state/` for git review. It is not `extract` (config seed) and not `diff` (desired vs actual config). Packaged golden is trial-balance via contract `inquire:` (`EndingBalance` fixed-point); inventory-summary is not golden this pass. `gi:` stays optional when a GI is V12-verified and **Expose via OData** is on (`params` fail-closed vs `$metadata`). After a cold `acu run scenario/ && acu snapshot`, warm `acu run scenario/10-seed-capital.yaml && acu snapshot --assert-unchanged` is the once-class gate (full scenario re-run is additive and moves cash observations on the TB).
+
+**Migration (path hard-cut):** bare defaults are `config/snapshot/` (views) and `state/` (observations). Root `snapshot/` and `snapshots/` are no longer defaulted — move files or pass explicit path args.
+
 ### Seed `endpoint:` symbols
 
 Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.
@@ -279,11 +284,13 @@ Configuration is one file: a decrypted `.env` at the repo root names the instanc
 
 The tier is self-contained.
 Each run scaffolds a synthetic single-org company from the packaged `acu config init` templates into a temporary directory, copies the real `.env` into it, and runs the installed `acu` binary from there — no data repo, no pre-existing fixtures on the instance.
-Scratch tenants (`E2E`, `E2EA`, `E2EB`) are created on the way in and always deleted on the way out, so nothing persists.
+Scratch tenants (`E2E`, `E2EA`, `E2EB`, `E2ESCEN`) are created on the way in and always deleted on the way out, so nothing persists.
+The packaged full `config init` seed (under `config/`) is the only scaffold.
 
 ```sh
 gmake e2e                                # whole tier, about 20 minutes
-gmake e2e FILE=test_provision_lifecycle  # one file, by stem or path
+gmake e2e FILE=test_provision_lifecycle  # apply/diff focus
+gmake e2e FILE=test_scenario_lifecycle   # scenario + snapshot focus
 ```
 
 ## License

{acumatica_cli-0.12.1 → acumatica_cli-0.13.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.12.1"
+version = "0.13.1"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 license = "PolyForm-Noncommercial-1.0.0"

{acumatica_cli-0.12.1 → acumatica_cli-0.13.1}/src/acumatica_cli/cli.py

@@ -12,10 +12,9 @@ import click
 import httpx
 from click.shell_completion import get_completion_class
 
-from . import bootstrap, extract, firstlogin, output, run, seed
+from . import bootstrap, extract, firstlogin, output, run, seed, snapshot
 from .client import AcumaticaClient
 from .config import (
-    INIT_FLAVORS,
     Instance,
     data_root,
     find_data_root,
@@ -411,45 +410,33 @@ def config_group() -> None:
     help="Hostname substituted into the scaffolded .env ACU_BASE_URL/ACU_SSH "
     "values (default: a placeholder)",
 )
-@click.option(
-    "--flavor",
-    type=click.Choice(sorted(INIT_FLAVORS), case_sensitive=True),
-    default=None,
-    help="Template set: omit for finance-minimal (default, offline e2e); "
-    "distribution = full virgin-tenant demo seed (master/, scenario/, "
-    "expanded COA/features)",
-)
 @click.argument(
     "directory", required=False, type=click.Path(file_okay=False, path_type=Path)
 )
-def config_init(host: str | None, flavor: str | None, directory: Path | None) -> None:
-    """Scaffold a data repo: .env, .gitignore, bootstrap/, baseline/, setup/.
+def config_init(host: str | None, directory: Path | None) -> None:
+    """Scaffold a data repo: .env, target.yaml, config/ seed, scenario/.
 
     Templates ship with the package; every value is a placeholder or a
-    verified minimal example - no secrets. Both flavors scaffold the full
-    company ``bootstrap/project.xml`` (Bootstrap/1.0.0). ``--flavor
-    distribution`` scaffolds under ``config/`` + lifecycle ``scenario/``
-    + README (V28/T87). Existing files are never overwritten (reported as
-    skipped). DIRECTORY defaults to the current directory and is created
-    if absent. No git init, no gpg.
+    verified example - no secrets. Single full seed under ``config/``
+    (bootstrap/baseline/setup/master) + lifecycle ``scenario/`` +
+    ``config/snapshot/`` + README; full company ``project.xml``
+    (Bootstrap/1.0.0). No ``--flavor`` (V28/T108). Existing files are
+    never overwritten (reported as skipped). DIRECTORY defaults to the
+    current directory and is created if absent. No git init, no gpg.
     """
     target = directory or Path.cwd()
-    for action, path in scaffold(target, host=host, flavor=flavor):
+    for action, path in scaffold(target, host=host):
         suffix = " (exists)" if action == "skip" else ""
         output.data(f"{action} {path}{suffix}")
-    # next-step cmds (issue #18/#19): operator rebuild order after scaffold
+    # next-step cmds: operator rebuild order after scaffold (V28)
     output.data("")
     output.data("next:")
     output.data("  1. edit .env (set ACU_PASSWORD, ACU_TENANT; keep ACU_API_VERSION)")
     output.data("  2. acu config check")
     output.data("  3. acu bootstrap          # or: acu tenant create ... (SSH)")
-    if flavor == "distribution":
-        output.data("  4. acu apply config/")
-        output.data("  5. acu run scenario/")
-        output.data("  6. acu diff config/")
-    else:
-        output.data("  4. acu apply")
-        output.data("  5. acu diff")
+    output.data("  4. acu apply config/")
+    output.data("  5. acu run scenario/")
+    output.data("  6. acu diff config/")
 
 
 @config_group.command("show")
@@ -695,7 +682,7 @@ def default_seed_dirs() -> tuple[Path, ...]:
     When the data-repo ``config/`` has any SEED_DIRS child, only those
     ``config/<name>/`` paths are returned (dual layout never merges with
     root). Else root ``bootstrap/``…``master/`` for present names
-    (finance-minimal). The data repo is the .env dir (V3 walk-up). None
+    (legacy root layout). The data repo is the .env dir (V3 walk-up). None
     existing is an error - an empty default would make a bare run a silent
     no-op. Paths come back relative to cwd so a bare run prints exactly
     what naming the dirs would.
@@ -946,3 +933,79 @@ def _exit_on_drift(inst: Instance, drifts: list[str], files: int) -> None:
             output.data(f"  {line}")
         raise SystemExit(2)
     output.success(f"no drift on {inst.tenant} ({inst.base_url}, {files} file(s))")
+
+
+@cli.command("snapshot")
+@click.argument(
+    "files", nargs=-1, required=False, type=click.Path(exists=True, path_type=Path)
+)
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Observation output directory (default: state/)",
+)
+@click.option(
+    "--diff",
+    "do_diff",
+    is_flag=True,
+    help="Compare live vs disk; write nothing (exit 0 either way)",
+)
+@click.option(
+    "--assert-unchanged",
+    is_flag=True,
+    help="Like --diff, but exit 2 when state moved (idempotence gate)",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Resolve views and validate sources without HTTP",
+)
+@pass_instance
+def snapshot_cmd(
+    inst: Instance,
+    files: tuple[Path, ...],
+    out_dir: Path | None,
+    do_diff: bool,
+    assert_unchanged: bool,
+    dry_run: bool,
+) -> None:
+    """Capture live derived state into committed observation files.
+
+    FILES are snapshot view YAML files or directories. Omitted, they default
+    to the data repo's config/snapshot/ directory (hard-cut; no root
+    snapshot/ fallback). Default write target is state/ (--out; no
+    snapshots/ fallback). Bare capture writes observations (change is
+    fine). --diff compares live to disk without writing.
+    --assert-unchanged is the warm-run idempotence gate (exit 2 when
+    moved). Never writes seed trees or endpoint: symbols (V32). Exit 0
+    ok, 1 op fail, 2 only under --assert-unchanged when state moved.
+    """
+    assert_target_compatible(inst)
+    if not files:
+        default = data_root() / "config" / "snapshot"
+        if not default.is_dir():
+            raise SystemExit(f"{default}: snapshot directory does not exist")
+        files = (Path(os.path.relpath(default)),)
+    paths = snapshot.expand_view_files(files)
+    views = [snapshot.load_view(path) for path in paths]
+    dest = out_dir if out_dir is not None else Path("state")
+    if dry_run:
+        code = snapshot.run_views(None, views, out_dir=dest, mode="dry")
+    else:
+        mode = "assert" if assert_unchanged else "diff" if do_diff else "write"
+        with AcumaticaClient(inst) as client:
+            code = snapshot.run_views(client, views, out_dir=dest, mode=mode)
+    if code:
+        raise SystemExit(code)
+    if dry_run:
+        return
+    if assert_unchanged:
+        output.success(f"{len(views)} snapshot(s) unchanged on {inst.tenant}")
+    elif do_diff:
+        output.success(f"{len(views)} snapshot(s) compared on {inst.tenant}")
+    else:
+        output.success(
+            f"{len(views)} snapshot(s) written under {dest} on {inst.tenant}"
+        )

{acumatica_cli-0.12.1 → acumatica_cli-0.13.1}/src/acumatica_cli/client.py

@@ -538,3 +538,27 @@ class AcumaticaClient:
         return self._checked(
             self._http.post("/CustomizationApi/publishEnd", json={})
         ).json()
+
+    # -- OData Generic Inquiry (snapshot gi: source; V33) --
+
+    def _odata_gi_root(self) -> str:
+        """24R2+ OData GI service root ``/t/<tenant>/api/odata/gi`` (V33)."""
+        tenant = quote(self.instance.tenant, safe="")
+        return f"/t/{tenant}/api/odata/gi"
+
+    def odata_gi_metadata(self, name: str) -> str:
+        """GET OData GI service ``$metadata`` XML (V33 param validation).
+
+        ``name`` is reserved for future per-GI metadata URLs; the 24R2
+        service exposes one EDMX document at the service root.
+        """
+        del name  # service-level metadata; per-GI filter is validate_gi_params
+        r = self._checked(self._http.get(f"{self._odata_gi_root()}/$metadata"))
+        return r.text
+
+    def odata_gi(self, name: str, params: dict[str, str] | None = None) -> Any:
+        """GET OData GI rows as JSON (requires Expose via OData on the GI)."""
+        gi = quote(name, safe="")
+        return self._checked(
+            self._http.get(f"{self._odata_gi_root()}/{gi}", params=params)
+        ).json()