acumatica-cli 0.8.0__tar.gz → 0.8.1__tar.gz

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.8.0
+Version: 0.8.1
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -10,7 +10,7 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: pydantic-settings>=2.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13
-Requires-Python: >=3.12
+Requires-Python: >=3.14
 Project-URL: Homepage, https://lab5.ca
 Project-URL: Repository, https://github.com/kborovik/acumatica-cli
 Description-Content-Type: text/markdown
@@ -21,22 +21,6 @@ Description-Content-Type: text/markdown
 
 **No UI clicks, no Configuration Wizard.**
 
-## How it works
-
-1. **Extract** the target Acumatica deployment with `acu extract` — its configuration becomes YAML, config as code.
-2. **Develop** changes in the YAML, in git: edit, review, version.
-3. **Re-deploy** with `acu apply`, then prove the live tenant matches the code with `acu diff`.
-
-Four commands do the work, and every one is safe to re-run:
-
-- **`acu tenant create`** — creates a tenant and bootstraps it in one step, ready for `apply`.
-  Re-running it against an existing tenant republishes the bootstrap package instead of failing.
-- **`acu apply`** — pushes your YAML into the tenant as keyed upserts.
-  Running it twice changes nothing.
-- **`acu diff`** — compares your YAML against the live tenant and exits with code 2 on drift.
-- **`acu extract`** — reads a configured tenant and writes the YAML file set back out, the inverse of `apply`.
-  Existing files are skipped unless `--force`.
-
 > **Tested against** Acumatica ERP **26.101.0225** on Windows Server 2025,
 > contract REST endpoint **25.200.001**. Other versions will likely work,
 > but only this combination is verified.
@@ -75,6 +59,7 @@ 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)
 ├── 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)
@@ -86,25 +71,31 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ```
 
 `apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
+`run` called without FILES defaults to `scenario/`.
 `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, which `acu config init` scaffolds:
+Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
 
 | Path         | What it holds                                                              |
 | ------------ | -------------------------------------------------------------------------- |
 | `bootstrap/` | what makes a virgin tenant configurable: features, company, credit terms   |
 | `baseline/`  | reference data: subaccounts, chart of accounts, ledger, units of measure   |
 | `setup/`     | one-time actions: financial year, master calendar, open periods            |
+| `scenario/`  | transaction scenarios for `acu run`: purchase, build, sell flows            |
 | `.env`       | where to apply and who signs in, every key an `ACU_*` variable             |
 
 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.
 
+Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
+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 a scenario re-runs safely on a warm tenant.
+
 ## Installation
 
-Requires Python 3.12 or newer.
+Requires Python 3.14 or newer.
 
 ```sh
 uv tool install acumatica-cli
@@ -148,9 +139,9 @@ acu apply --dry-run    # show what would be written, write nothing
 `acu` talks to an instance over two independent channels:
 
 - **Control plane (SSH):** `acu tenant` runs `ac.exe -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see [`docs/ac-exe.md`](docs/ac-exe.md).
-- **Data plane (REST):** `acu apply`, `diff`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
+- **Data plane (REST):** `acu apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
 
-If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+If you never touch `acu tenant`, you never need SSH — every other command is pure REST.
 
 ## SSH setup (control plane)
 

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/README.md

@@ -4,22 +4,6 @@
 
 **No UI clicks, no Configuration Wizard.**
 
-## How it works
-
-1. **Extract** the target Acumatica deployment with `acu extract` — its configuration becomes YAML, config as code.
-2. **Develop** changes in the YAML, in git: edit, review, version.
-3. **Re-deploy** with `acu apply`, then prove the live tenant matches the code with `acu diff`.
-
-Four commands do the work, and every one is safe to re-run:
-
-- **`acu tenant create`** — creates a tenant and bootstraps it in one step, ready for `apply`.
-  Re-running it against an existing tenant republishes the bootstrap package instead of failing.
-- **`acu apply`** — pushes your YAML into the tenant as keyed upserts.
-  Running it twice changes nothing.
-- **`acu diff`** — compares your YAML against the live tenant and exits with code 2 on drift.
-- **`acu extract`** — reads a configured tenant and writes the YAML file set back out, the inverse of `apply`.
-  Existing files are skipped unless `--force`.
-
 > **Tested against** Acumatica ERP **26.101.0225** on Windows Server 2025,
 > contract REST endpoint **25.200.001**. Other versions will likely work,
 > but only this combination is verified.
@@ -58,6 +42,7 @@ 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)
 ├── 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)
@@ -69,25 +54,31 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ```
 
 `apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
+`run` called without FILES defaults to `scenario/`.
 `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, which `acu config init` scaffolds:
+Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
 
 | Path         | What it holds                                                              |
 | ------------ | -------------------------------------------------------------------------- |
 | `bootstrap/` | what makes a virgin tenant configurable: features, company, credit terms   |
 | `baseline/`  | reference data: subaccounts, chart of accounts, ledger, units of measure   |
 | `setup/`     | one-time actions: financial year, master calendar, open periods            |
+| `scenario/`  | transaction scenarios for `acu run`: purchase, build, sell flows            |
 | `.env`       | where to apply and who signs in, every key an `ACU_*` variable             |
 
 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.
 
+Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
+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 a scenario re-runs safely on a warm tenant.
+
 ## Installation
 
-Requires Python 3.12 or newer.
+Requires Python 3.14 or newer.
 
 ```sh
 uv tool install acumatica-cli
@@ -131,9 +122,9 @@ acu apply --dry-run    # show what would be written, write nothing
 `acu` talks to an instance over two independent channels:
 
 - **Control plane (SSH):** `acu tenant` runs `ac.exe -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see [`docs/ac-exe.md`](docs/ac-exe.md).
-- **Data plane (REST):** `acu apply`, `diff`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
+- **Data plane (REST):** `acu apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
 
-If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+If you never touch `acu tenant`, you never need SSH — every other command is pure REST.
 
 ## SSH setup (control plane)
 

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "acumatica-cli"
-version = "0.8.0"
+version = "0.8.1"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.14"
 dependencies = [
     "click>=8.1",
     "httpx>=0.27",
@@ -41,7 +41,7 @@ markers = [
 
 [tool.basedpyright]
 typeCheckingMode = "strict"
-pythonVersion = "3.12"
+pythonVersion = "3.14"
 include = ["src/acumatica_cli/", "tests/"]
 reportMissingTypeStubs = false
 reportUnknownVariableType = false
@@ -52,7 +52,7 @@ reportUnknownLambdaType = false
 reportUnusedFunction = "warning"
 
 [tool.ruff]
-target-version = "py312"
+target-version = "py314"
 src = ["src"]
 
 [tool.ruff.format]

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/bootstrap.py

@@ -150,7 +150,7 @@ def _published_description(client: AcumaticaClient) -> str | None:
     try:
         with zipfile.ZipFile(io.BytesIO(content)) as zf:
             root = ET.fromstring(zf.read("project.xml"))
-    except (zipfile.BadZipFile, KeyError, ET.ParseError):
+    except zipfile.BadZipFile, KeyError, ET.ParseError:
         return None
     return root.get("description")
 

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/cli.py

@@ -379,12 +379,13 @@ def config_check(ctx: click.Context) -> None:
 
     Dependency order: discovery (.env walk-up + parse + ACU_BASE_URL), then
     secrets (ACU_PASSWORD resolved), then REST (login, landed-tenant verify,
-    logout) and ssh (trivial remote command) probed independently - a
-    discovery or secrets failure stops, a REST failure still probes ssh and
+    logout) and ssh probed independently - ssh set → trivial remote; ssh
+    unset → skip (ACU_SSH optional, V3 hosted path), never fail. A discovery
+    or secrets failure stops; a REST failure still probes ssh when set and
     vice versa. Discovery is lax (V3): no .env passes when --url covers
     base_url, and flags-only runs (no .env anywhere) are valid. Writes
-    nothing: no PUTs, no tenant CRUD. Exit 0 when every probe passes, 1 on
-    any failure.
+    nothing: no PUTs, no tenant CRUD. Exit 0 when every non-skipped probe
+    passes, 1 on any failure.
     """
     overrides: dict[str, str] = ctx.obj or {}
     # discovery (V3): lax walk-up + parse; base_url (the primary identity
@@ -432,12 +433,16 @@ def config_check(ctx: click.Context) -> None:
     except (RuntimeError, httpx.HTTPError) as exc:
         output.data(f"fail rest: {exc}")
         failed = True
-    try:
-        TenantManager(inst).ping()
-        output.data(f"ok ssh ({inst.ssh})")
-    except RuntimeError as exc:
-        output.data(f"fail ssh: {exc}")
-        failed = True
+    if not inst.ssh:
+        # V3/I.cmd: ACU_SSH optional — hosted data-plane path skips, never fails
+        output.data("skip ssh (ACU_SSH not set)")
+    else:
+        try:
+            TenantManager(inst).ping()
+            output.data(f"ok ssh ({inst.ssh})")
+        except RuntimeError as exc:
+            output.data(f"fail ssh: {exc}")
+            failed = True
     if failed:
         raise SystemExit(1)
 

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/client.py

@@ -94,7 +94,7 @@ class AcumaticaClient:
             base_url=instance.base_url, timeout=timeout, transport=transport
         )
 
-    def __enter__(self) -> "AcumaticaClient":
+    def __enter__(self) -> AcumaticaClient:
         # tenant guard (V5, docs/rest-api.md): an omitted or empty tenant is
         # the one login the server still routes silently — to the default
         # tenant. Defense-in-depth vs wrong-tenant writes: every data-plane

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/config.py

@@ -5,9 +5,10 @@ env prefix ``ACU_``, and the sole config file is ``.env`` (found by walking
 up from cwd) carrying where + secrets as ``ACU_*`` vars. The file is
 optional - flags plus the process environment can supply the full config.
 Per key the first set value wins: flag, ``ACU_*`` var (process environment
-over a found ``.env``), code default. ``base_url`` and ``ssh`` are the only
-required address values - one explicit address per plane (V1), never
-derived; the password must resolve via ``--password`` or ``ACU_PASSWORD``.
+over a found ``.env``), code default. ``base_url`` is the only required
+address (REST data plane); ``ssh`` is optional control-plane address
+(empty = data-plane only; tenant cmds hard-error when unresolved — V1/V3).
+The password must resolve via ``--password`` or ``ACU_PASSWORD``.
 """
 
 from collections.abc import Iterator, Mapping
@@ -51,11 +52,12 @@ INIT_TEMPLATES = (
 class Instance(BaseSettings):
     """The resolved target: flags over ACU_* vars (.env or process) over defaults.
 
-    One explicit address per plane (V1), no derivation: ``base_url`` is the
-    REST root (scheme + host + site path), ``ssh`` the control-plane
-    ``user@host``. Install-layout values are module constants, not fields.
-    Unknown ``ACU_*`` vars are ignored, never errors - the environment and
-    ``.env`` legitimately carry non-config vars (``ACU_DEBUG``).
+    Explicit addresses, no derivation (V1): ``base_url`` is the REST root
+    (scheme + host + site path); ``ssh`` is the optional control-plane
+    ``user@host`` (empty = data-plane only). Install-layout values are
+    module constants, not fields. Unknown ``ACU_*`` vars are ignored,
+    never errors - the environment and ``.env`` legitimately carry
+    non-config vars (``ACU_DEBUG``).
     """
 
     model_config = SettingsConfigDict(
@@ -65,7 +67,7 @@ class Instance(BaseSettings):
     )
 
     base_url: str  # REST root: scheme + host + site path
-    ssh: str  # control plane: full user@host
+    ssh: str = ""  # control plane: full user@host; empty = data-plane only
     tenant: str = ""
     api_version: str = "25.200.001"  # V11: /entity/Default/<api_version>/
     user: str = "admin"  # ACU_USER; the --username flag maps here
@@ -76,8 +78,8 @@ class Instance(BaseSettings):
     @model_validator(mode="before")
     @classmethod
     def _blank_required_is_unset(cls, data: Any) -> Any:
-        # a blank ACU_BASE_URL= / ACU_SSH= line reads as missing, not as an
-        # empty address - the hard error names the unresolved key (V3)
+        # blank ACU_BASE_URL= / ACU_SSH= reads as unset (V3): base_url then
+        # fails required; ssh falls through to the empty default (optional)
         if isinstance(data, dict):
             for key in ("base_url", "ssh"):
                 if data.get(key) == "":
@@ -161,8 +163,9 @@ def load_instance(overrides: Mapping[str, str | None] | None = None) -> Instance
     ``overrides`` carries the global flags keyed by Instance field name;
     per key the first set value wins (flag, ACU_* var - process environment
     over a found .env - code default). No .env is fine (V3): the hard error
-    comes only when a required value (base_url, ssh, password) is still
-    unresolved after the merge, naming the missing key.
+    comes only when a required value (base_url, password) is still
+    unresolved after the merge, naming the missing key. ``ssh`` is optional
+    (hosted / data-plane-only path); tenant cmds hard-error when it is empty.
     """
     flags = {k: v for k, v in dict(overrides or {}).items() if v is not None}
     root = find_data_root()

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/extract.py

@@ -66,7 +66,7 @@ class EntitySpec(Model):
         return BOOTSTRAP_ENDPOINT if v == "bootstrap" else v
 
     @model_validator(mode="after")
-    def _strip_include_exclusive(self) -> "EntitySpec":
+    def _strip_include_exclusive(self) -> EntitySpec:
         if self.strip and self.include:
             raise ValueError("strip and include are mutually exclusive")
         return self
@@ -96,7 +96,7 @@ class Manifest(Model):
     setup: list[SetupSynth] = Field(default_factory=list)
 
     @model_validator(mode="after")
-    def _self_consistent(self) -> "Manifest":
+    def _self_consistent(self) -> Manifest:
         # V20 by construction: an emitted file for an entity both endpoints
         # serve must carry an endpoint, or load_baseline rejects it
         for spec in self.entities:

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/output.py

@@ -6,6 +6,7 @@ and spinners on a TTY and degrades to plain deterministic text when piped
 stderr carries status, warnings, and errors.
 """
 
+import os
 from collections.abc import Generator, Iterable
 from contextlib import contextmanager
 
@@ -13,8 +14,30 @@ from rich import box
 from rich.console import Console
 from rich.table import Table
 
-out = Console(markup=False, emoji=False, highlight=False)
-err = Console(stderr=True, markup=False, emoji=False, highlight=False)
+
+def _force_terminal() -> bool | None:
+    """Map NO_COLOR / FORCE_COLOR to rich's force_terminal flag.
+
+    None leaves auto-detect (isatty). False forces plain/piped rendering.
+    True forces TTY chrome even when piped.
+
+    Rich treats any non-empty FORCE_COLOR as "on", so FORCE_COLOR=0 would
+    otherwise enable color. We treat empty and "0" as off (force-color.org).
+    NO_COLOR (any value) always wins and forces plain output (no-color.org).
+    """
+    if "NO_COLOR" in os.environ:
+        return False
+    force = os.environ.get("FORCE_COLOR")
+    if force is not None:
+        return force not in ("", "0")
+    return None
+
+
+_force = _force_terminal()
+out = Console(markup=False, emoji=False, highlight=False, force_terminal=_force)
+err = Console(
+    stderr=True, markup=False, emoji=False, highlight=False, force_terminal=_force
+)
 
 
 def data(msg: str) -> None:

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/run.py

@@ -99,7 +99,7 @@ class Step(Model):
     endpoint: str | None = None
 
     @model_validator(mode="after")
-    def _one_op(self) -> "Step":
+    def _one_op(self) -> Step:
         ops = [op for op in (self.put, self.action, self.get) if op is not None]
         if len(ops) > 1:
             raise ValueError(f"step '{self.id}': put, action, get are exclusive")
@@ -134,7 +134,7 @@ class Expect(Model):
     endpoint: str | None = None
 
     @model_validator(mode="after")
-    def _one_kind(self) -> "Expect":
+    def _one_kind(self) -> Expect:
         if (self.get is None) == (self.inquire is None):
             raise ValueError("expect: exactly one of get, inquire")
         if self.get is not None and self.fields is None:
@@ -164,7 +164,7 @@ class Scenario(Model):
     expect: list[Expect] = Field(default_factory=list)
 
     @model_validator(mode="after")
-    def _unique_step_ids(self) -> "Scenario":
+    def _unique_step_ids(self) -> Scenario:
         seen: set[str] = set()
         for step in self.steps:
             if step.id in seen:

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/seed.py

@@ -109,7 +109,7 @@ class BaselineFile(Model):
         return v if isinstance(v, list) else [v]
 
     @model_validator(mode="after")
-    def _keys_identify_records(self) -> "BaselineFile":
+    def _keys_identify_records(self) -> BaselineFile:
         # V25: the declared key tuple must uniquely identify records - a
         # dup-keyed file diffs as permanent false drift and apply collapses
         # the dup records into one PUT target (B21)

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/env

@@ -1,8 +1,9 @@
 # scaffolded by `acu config init` - the sole config file: where + secrets,
 # every key an ACU_* var; print the fully resolved document with:
 #   acu config show
-# ACU_BASE_URL (REST root) and ACU_SSH (control-plane user@host) are the
-# required addresses; the rest are code defaults you can override here.
+# ACU_BASE_URL (REST root) is required; ACU_SSH (control-plane user@host)
+# is optional - leave blank for hosted / data-plane-only (tenant CRUD still
+# needs it). The rest are code defaults you can override here.
 # Keep this file out of git (the scaffolded .gitignore already lists it;
 # encrypt at rest, e.g. .env.gpg).
 ACU_BASE_URL=http://erp.example.com/AcumaticaERP

{acumatica_cli-0.8.0 → acumatica_cli-0.8.1}/src/acumatica_cli/tenant.py

@@ -28,6 +28,14 @@ class TenantManager:
     """Tenant CRUD via SSH to the Windows guest."""
 
     def __init__(self, instance: Instance):
+        # control-plane address is optional on Instance (hosted path, V3);
+        # tenant CRUD still needs it - hard-error naming the key before any
+        # remote (I.cmd), never an empty ssh argv
+        if not instance.ssh:
+            raise SystemExit(
+                "ACU_SSH not set (pass --ssh, "
+                "or put ACU_SSH in .env or the environment)"
+            )
         self.instance = instance
 
     def _ssh(self, command: str) -> str: