acumatica-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{acumatica_cli-0.6.0 → acumatica_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>

{acumatica_cli-0.6.0 → acumatica_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 readme = "README.md"

{acumatica_cli-0.6.0 → acumatica_cli-0.7.0}/src/acumatica_cli/cli.py

@@ -12,7 +12,7 @@ import click
 import httpx
 from click.shell_completion import get_completion_class
 
-from . import bootstrap, extract, firstlogin, output, seed
+from . import bootstrap, extract, firstlogin, output, run, seed
 from .client import AcumaticaClient
 from .config import (
     Instance,
@@ -557,6 +557,42 @@ def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
     _exit_on_drift(inst, drifts, len(paths))
 
 
+@cli.command("run")
+@click.argument(
+    "files", nargs=-1, required=False, type=click.Path(exists=True, path_type=Path)
+)
+@click.option("--dry-run", is_flag=True, help="Parse and list steps without any HTTP")
+@pass_instance
+def run_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
+    """Execute transaction scenario YAML against the live tenant.
+
+    FILES are scenario YAML files or directories containing them. Omitted,
+    they default to the data repo's scenario/ directory. Transactions are
+    executed forward (the server assigns document numbers), never upserted;
+    delta expectations snapshot before the first step and compare after the
+    last, so a scenario re-runs safely on a warm tenant. Exit 0 when every
+    expectation holds, 1 on any step error or expectation miss.
+    """
+    if not files:
+        default = data_root() / "scenario"
+        if not default.is_dir():
+            raise SystemExit(f"{default}: scenario directory does not exist")
+        files = (Path(os.path.relpath(default)),)
+    paths = expand_files(files)
+    scenarios = [run.load_scenario(path) for path in paths]
+    ok = True
+    if dry_run:
+        for scenario in scenarios:
+            run.run(None, scenario, dry_run=True)
+    else:
+        with AcumaticaClient(inst) as client:
+            for scenario in scenarios:
+                ok = run.run(client, scenario) and ok
+    if not ok:
+        raise SystemExit(1)
+    output.success(f"{len(scenarios)} scenario(s) passed on {inst.tenant}")
+
+
 def _complete_only(
     _ctx: click.Context, _param: click.Parameter, incomplete: str
 ) -> list[str]:

{acumatica_cli-0.6.0 → acumatica_cli-0.7.0}/src/acumatica_cli/client.py

@@ -230,11 +230,21 @@ class AcumaticaClient:
         return self._checked(self._http.get(self._url("swagger.json"))).content
 
     def put(
-        self, entity: str, record: dict[str, Any], endpoint: str | None = None
+        self,
+        entity: str,
+        record: dict[str, Any],
+        endpoint: str | None = None,
+        params: dict[str, str] | None = None,
     ) -> dict[str, Any]:
-        """Upsert by the entity's key fields — the idempotence primitive."""
+        """Upsert by the entity's key fields — the idempotence primitive.
+
+        `params` carries OData query options — the contract-inquiry idiom
+        (T62) is a PUT of the parameter record with `$expand=Results`.
+        """
         return self._checked(
-            self._http.put(self._url(entity, endpoint), json=wrap(record))
+            self._http.put(
+                self._url(entity, endpoint), json=wrap(record), params=params
+            )
         ).json()
 
     # seconds between polls of a long-running action's status URL; module

acumatica_cli-0.7.0/src/acumatica_cli/run.py

@@ -0,0 +1,369 @@
+"""Transaction scenarios: scenario/*.yaml executed against the live tenant.
+
+`acu run` is the third data-plane verb (SPEC I.cmd): apply/diff own
+configuration (keyed idempotent upserts), run owns transactions - the
+server assigns document numbers, so a scenario is executed forward,
+never upserted. The scenario file is the contract for the future AI
+scenario generator: declarative steps, checkable expectations.
+
+Scenario file format (SPEC I.data):
+
+    scenario: buy-build-sell
+    description: Buy parts -> assemble kits -> sell -> collect
+    steps:
+      - id: po-shenzhen
+        put: PurchaseOrder
+        record:
+          VendorID: SHENZHEN
+          Details:
+            - { InventoryID: MB-CM4, OrderQty: 25 }
+        capture: { OrderNbr: po_shenzhen }     # server-assigned -> ${var}
+      - id: release
+        action: { entity: PurchaseReceipt, name: ReleasePurchaseReceipt }
+        record: { ReceiptNbr: "${rcpt}" }
+        wait:                                   # poll until field match
+          entity: PurchaseReceipt
+          keys: ["${rcpt}"]
+          until: { Status: Released }
+    expect:
+      - get: { entity: Payment, keys: [Payment, "${pmt}"] }
+        fields: { Status: Closed }
+      - inquire: AccountSummaryInquiry          # delta = post - pre
+        parameters: { Ledger: ACTUAL, Period: "062026" }
+        match: { Account: "40000" }
+        delta: { EndingBalance: 4138.00 }
+
+Steps run in order; `capture` lifts server-assigned fields into ${var}
+tokens for later steps. `expect` delta assertions snapshot before the
+first step and re-probe after the last, comparing the difference - the
+scenario re-runs safely on a warm tenant (document numbers differ, the
+deltas hold). `get` assertions are absolute (statuses of documents
+created in this run). Exit 0 = every expectation holds; 1 = any step
+error or expectation miss (2 stays diff's drift code).
+"""
+
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import Field, ValidationError, model_validator
+
+from . import output
+from .client import AcumaticaClient, unwrap
+from .models import Model, validation_summary
+from .seed import _norm  # pyright: ignore[reportPrivateUsage]
+
+_VAR = re.compile(r"\$\{([A-Za-z0-9_]+)\}")
+
+
+class ActionSpec(Model):
+    """The contract action a step invokes: entity + action name."""
+
+    entity: str
+    name: str
+
+
+class WaitSpec(Model):
+    """Poll a record by key URL until every `until` field matches."""
+
+    entity: str
+    keys: list[Any]
+    until: dict[str, Any]
+    timeout: float = 120.0
+    endpoint: str | None = None
+
+
+class Step(Model):
+    """One scenario step: exactly one op (put | action | wait-only)."""
+
+    id: str
+    put: str | None = None
+    action: ActionSpec | None = None
+    record: dict[str, Any] | None = None
+    parameters: dict[str, Any] | None = None
+    capture: dict[str, str] | None = None  # {Field: var_name}
+    wait: WaitSpec | None = None
+    endpoint: str | None = None
+
+    @model_validator(mode="after")
+    def _one_op(self) -> "Step":
+        ops = [op for op in (self.put, self.action) if op is not None]
+        if len(ops) > 1:
+            raise ValueError(f"step '{self.id}': put and action are exclusive")
+        if not ops and self.wait is None:
+            raise ValueError(f"step '{self.id}': needs one of put, action, wait")
+        if self.put is not None and self.record is None:
+            raise ValueError(f"step '{self.id}': put needs a record")
+        if self.action is not None and self.record is None:
+            raise ValueError(f"step '{self.id}': action needs a record")
+        if self.capture is not None and self.put is None:
+            raise ValueError(f"step '{self.id}': capture rides a put step")
+        return self
+
+
+class GetSpec(Model):
+    """Key-URL record address for a get expectation."""
+
+    entity: str
+    keys: list[Any]
+    endpoint: str | None = None
+
+
+class Expect(Model):
+    """One expectation: absolute `get` fields or `inquire` deltas."""
+
+    get: GetSpec | None = None
+    fields: dict[str, Any] | None = None
+    inquire: str | None = None
+    parameters: dict[str, Any] | None = None
+    match: dict[str, Any] | None = None
+    delta: dict[str, float] | None = None
+    endpoint: str | None = None
+
+    @model_validator(mode="after")
+    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:
+            raise ValueError("expect: get needs fields")
+        if self.inquire is not None and self.delta is None:
+            raise ValueError("expect: inquire needs delta")
+        return self
+
+    def label(self) -> str:
+        """Human-readable expectation address for report lines."""
+        if self.get is not None:
+            keys = ", ".join(str(k) for k in self.get.keys)
+            return f"{self.get.entity} [{keys}]"
+        match = ""
+        if self.match:
+            match = f" [{', '.join(f'{k}={v}' for k, v in self.match.items())}]"
+        return f"{self.inquire}{match}"
+
+
+class Scenario(Model):
+    """A parsed scenario YAML: named steps plus expectations."""
+
+    path: Path
+    scenario: str
+    description: str | None = None
+    steps: list[Step]
+    expect: list[Expect] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _unique_step_ids(self) -> "Scenario":
+        seen: set[str] = set()
+        for step in self.steps:
+            if step.id in seen:
+                raise ValueError(f"duplicate step id '{step.id}'")
+            seen.add(step.id)
+        return self
+
+
+def load_scenario(path: Path) -> Scenario:
+    """Parse and validate one scenario YAML file."""
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    if not isinstance(data, dict):
+        raise SystemExit(f"{path}: expected a mapping at the top level")
+    try:
+        return Scenario.model_validate({"path": path, **data})
+    except ValidationError as exc:
+        raise SystemExit(f"{path}: {validation_summary(exc)}") from exc
+
+
+def _subst(value: Any, variables: dict[str, Any]) -> Any:
+    """Interpolate ${var} tokens; unknown names are a hard error."""
+
+    def _one(text: str) -> Any:
+        whole = _VAR.fullmatch(text)
+        if whole:  # whole-value token keeps the captured value's type
+            return _lookup(whole.group(1))
+        return _VAR.sub(lambda m: str(_lookup(m.group(1))), text)
+
+    def _lookup(name: str) -> Any:
+        if name not in variables:
+            raise SystemExit(
+                f"unknown scenario variable '${{{name}}}' - captured so far: "
+                f"{', '.join(sorted(variables)) or '(none)'}"
+            )
+        return variables[name]
+
+    if isinstance(value, str):
+        return _one(value)
+    if isinstance(value, dict):
+        return {k: _subst(v, variables) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_subst(v, variables) for v in value]
+    return value
+
+
+def _inquire(client: AcumaticaClient, expect: Expect) -> dict[str, float]:
+    """Probe a contract inquiry; sum each delta field over matching rows."""
+    assert expect.inquire is not None
+    assert expect.delta is not None
+    body = client.put(
+        expect.inquire,
+        expect.parameters or {},
+        endpoint=expect.endpoint,
+        params={"$expand": "Results"},
+    )
+    totals = dict.fromkeys(expect.delta, 0.0)
+    for row in body.get("Results") or []:
+        values = unwrap(row)
+        if expect.match and any(
+            field not in values or _norm(values[field]) != _norm(want)
+            for field, want in expect.match.items()
+        ):
+            continue
+        for field in totals:
+            totals[field] += float(values.get(field) or 0.0)
+    return totals
+
+
+def _wait(client: AcumaticaClient, spec: WaitSpec, variables: dict[str, Any]) -> None:
+    """Poll the record until every `until` field matches (live state, V4)."""
+    keys = _subst(spec.keys, variables)
+    until = _subst(spec.until, variables)
+    deadline = time.monotonic() + spec.timeout
+    state: dict[str, Any] | None = None
+    while time.monotonic() < deadline:
+        record = client.get_record(spec.entity, keys, spec.endpoint)
+        state = unwrap(record) if record is not None else None
+        if state is not None and all(
+            field in state and _norm(state[field]) == _norm(want)
+            for field, want in until.items()
+        ):
+            return
+        time.sleep(client.poll_interval)
+    raise RuntimeError(
+        f"wait timed out after {spec.timeout:g}s: {spec.entity} "
+        f"{keys} never reached {until} (last state: "
+        + (
+            ", ".join(f"{k}={state.get(k)!r}" for k in until)
+            if state is not None
+            else "record missing"
+        )
+        + ")"
+    )
+
+
+def _dry_run(scenario: Scenario) -> None:
+    """List steps and expectations without any HTTP."""
+    for step in scenario.steps:
+        op = (
+            f"PUT {step.put}"
+            if step.put
+            else f"invoke {step.action.entity}/{step.action.name}"
+            if step.action
+            else f"wait {step.wait.entity}"  # pyright: ignore[reportOptionalMemberAccess]
+        )
+        output.data(f"  would {op} [{step.id}]")
+    for expect in scenario.expect:
+        output.data(f"  would check {expect.label()}")
+
+
+def _run_step(client: AcumaticaClient, step: Step, variables: dict[str, Any]) -> None:
+    """Execute one step, folding captured fields into the variable set."""
+    if step.put is not None:
+        assert step.record is not None
+        body = client.put(
+            step.put, _subst(step.record, variables), endpoint=step.endpoint
+        )
+        output.data(f"  put {step.put} [{step.id}]")
+        for field, var in (step.capture or {}).items():
+            echoed = unwrap(body)
+            if field not in echoed:
+                raise RuntimeError(
+                    f"step '{step.id}': capture field '{field}' not in the PUT response"
+                )
+            variables[var] = echoed[field]
+    elif step.action is not None:
+        assert step.record is not None
+        client.invoke(
+            step.action.entity,
+            step.action.name,
+            _subst(step.record, variables),
+            _subst(step.parameters, variables),
+            step.endpoint,
+        )
+        output.data(f"  invoke {step.action.name} [{step.id}]")
+    if step.wait is not None:
+        _wait(client, step.wait, variables)
+        output.data(f"  wait ok [{step.id}]")
+
+
+def _check_get(
+    client: AcumaticaClient, expect: Expect, variables: dict[str, Any]
+) -> bool:
+    """Absolute field assertions on a key-URL record."""
+    assert expect.get is not None
+    assert expect.fields is not None
+    keys = _subst(expect.get.keys, variables)
+    # label from the substituted keys - the raw ${var} token is opaque
+    label = f"{expect.get.entity} [{', '.join(str(k) for k in keys)}]"
+    record = client.get_record(expect.get.entity, keys, expect.get.endpoint)
+    state = unwrap(record) if record is not None else {}
+    ok = True
+    for field, want in _subst(expect.fields, variables).items():
+        got = state.get(field)
+        if record is None or field not in state:
+            ok = False
+            output.data(f"  x {label}.{field}: not found")
+        elif _norm(got) != _norm(want):
+            ok = False
+            output.data(f"  x {label}.{field}: expected {want!r} got {got!r}")
+        else:
+            output.data(f"  + {label}.{field} = {want!r}")
+    return ok
+
+
+def _check_delta(
+    client: AcumaticaClient, expect: Expect, snapshot: dict[str, float]
+) -> bool:
+    """Delta assertions: post-run probe minus the pre-run snapshot."""
+    assert expect.delta is not None
+    after = _inquire(client, expect)
+    ok = True
+    for field, want in expect.delta.items():
+        got = after[field] - snapshot[field]
+        if abs(got - want) > 0.005:
+            ok = False
+            output.data(
+                f"  x {expect.label()}.{field}: expected delta {want:+g} got {got:+g}"
+            )
+        else:
+            output.data(f"  + {expect.label()}.{field} delta {want:+g}")
+    return ok
+
+
+def run(
+    client: AcumaticaClient | None, scenario: Scenario, dry_run: bool = False
+) -> bool:
+    """Execute the scenario; True when every step and expectation held.
+
+    client may be None only under dry_run - parsing and step listing
+    never touch HTTP (a preview costs nothing live). Delta expectations
+    snapshot BEFORE the first step (V4): the comparison is post minus
+    pre, so a warm tenant re-runs clean.
+    """
+    output.data(f"{scenario.path} -> {scenario.scenario}")
+    if dry_run:
+        _dry_run(scenario)
+        return True
+    assert client is not None  # non-dry-run callers pass a live session
+    before = [
+        _inquire(client, expect) if expect.inquire else {} for expect in scenario.expect
+    ]
+    variables: dict[str, Any] = {}
+    for step in scenario.steps:
+        _run_step(client, step, variables)
+    ok = True
+    for expect, snapshot in zip(scenario.expect, before, strict=True):
+        if expect.get is not None:
+            ok = _check_get(client, expect, variables) and ok
+        else:
+            ok = _check_delta(client, expect, snapshot) and ok
+    return ok