acumatica-cli 0.2.2__py3-none-any.whl

acumatica_cli/client.py

@@ -0,0 +1,251 @@
+"""Contract-based REST API session (see docs/rest-api.md for verified quirks)."""
+
+import base64
+import html
+import re
+from typing import Any
+
+import httpx
+
+from .config import Instance
+
+
+def wrap(record: dict[str, Any]) -> dict[str, Any]:
+    """Plain dict -> contract-API body: {"Field": {"value": ...}}."""
+    return {k: {"value": v} for k, v in record.items()}
+
+
+def unwrap(entity: dict[str, Any]) -> dict[str, Any]:
+    """Contract-API entity -> plain dict (top-level value fields only)."""
+    return {
+        k: v["value"] for k, v in entity.items() if isinstance(v, dict) and "value" in v
+    }
+
+
+class AcumaticaClient:
+    """Cookie-session client for the contract-based endpoint.
+
+    Use as a context manager: sessions count against the license, so logout
+    must run even on failure.
+    """
+
+    def __init__(
+        self,
+        instance: Instance,
+        timeout: float = 120.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self.instance = instance
+        self._http = httpx.Client(
+            base_url=instance.base_url, timeout=timeout, transport=transport
+        )
+
+    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
+        # session must name its tenant, so refuse before any HTTP happens.
+        if not self.instance.tenant:
+            raise RuntimeError(
+                f"no tenant set for {self.instance.host} - a session without "
+                "an explicit tenant silently lands on the default tenant; "
+                "set tenant in acu.yaml or pass -t/--tenant"
+            )
+        creds: dict[str, str] = {
+            "name": self.instance.username,
+            "password": self.instance.password,
+            "tenant": self.instance.tenant,
+        }
+        self._checked(self._http.post("/entity/auth/login", json=creds))
+        # tenant guard, landed side (V5, B5): login accepting the name proves
+        # nothing - a stale tenant map reroutes named logins to the default
+        # tenant, and a single-tenant instance accepts ANY name (both verified
+        # live, docs/rest-api.md). Verify where the session actually landed
+        # and refuse on mismatch; logout first, since __exit__ never runs
+        # when __enter__ raises (V6 - sessions count against the license).
+        try:
+            landed = self._landed_tenant()
+            if landed.casefold() != self.instance.tenant.casefold():
+                raise RuntimeError(
+                    f"tenant guard: asked for tenant {self.instance.tenant!r} "
+                    f"but the session landed on {landed!r} - the instance "
+                    "tenant map is stale or the tenant does not exist; check "
+                    "acu tenant list and recycle the app pool"
+                )
+        except BaseException:
+            self.__exit__()
+            raise
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        try:
+            # empty body sets Content-Length: 0 — IIS 411s without it
+            self._http.post("/entity/auth/logout", content=b"")
+        finally:
+            self._http.close()
+
+    def _landed_tenant(self) -> str:
+        """The tenant this session actually landed on (login name).
+
+        Verified vs 26.101.0225 (docs/rest-api.md): the contract API exposes
+        nothing tenant-identifying, but an authenticated GET of the sign-in
+        page renders a hidden ``txtSingleCompany`` input whose value is the
+        session tenant's login name in every observed state - multi-tenant,
+        single-tenant, and mid-reroute under a stale tenant map. The probe
+        does not disturb the session.
+        """
+        r = self._checked(self._http.get("/Frames/Login.aspx", follow_redirects=True))
+        m = re.search(r'id="txtSingleCompany" value="([^"]*)"', r.text)
+        if not m:
+            raise RuntimeError(
+                "tenant guard: /Frames/Login.aspx did not expose the landed "
+                "tenant (txtSingleCompany missing - page shape changed on "
+                "this build?); refusing the session rather than risking "
+                "wrong-tenant writes"
+            )
+        return html.unescape(m.group(1))
+
+    def _url(self, entity: str, endpoint: str | None = None) -> str:
+        return f"/entity/{endpoint or self.instance.endpoint}/{entity}"
+
+    @staticmethod
+    def _checked(r: httpx.Response) -> httpx.Response:
+        """Surface Acumatica's exceptionMessage instead of a bare status code."""
+        if r.is_error:
+            detail = ""
+            try:
+                body = r.json()
+                detail = body.get("exceptionMessage") or body.get("message") or ""
+            except Exception:
+                pass
+            raise RuntimeError(
+                f"{r.request.method} {r.request.url.path} -> {r.status_code}"
+                + (f": {detail}" if detail else "")
+            )
+        return r
+
+    def get_list(
+        self,
+        entity: str,
+        params: dict[str, str] | None = None,
+        endpoint: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """GET the entity's records, optionally narrowed with OData params.
+
+        endpoint overrides the instance's endpoint per call (bootstrap YAML
+        targets the custom Bootstrap endpoint; everything else defaults).
+        """
+        return self._checked(
+            self._http.get(self._url(entity, endpoint), params=params)
+        ).json()
+
+    def swagger(self) -> bytes:
+        """GET the endpoint's OpenAPI schema (swagger.json), raw bytes."""
+        return self._checked(self._http.get(self._url("swagger.json"))).content
+
+    def put(
+        self, entity: str, record: dict[str, Any], endpoint: str | None = None
+    ) -> dict[str, Any]:
+        """Upsert by the entity's key fields — the idempotence primitive."""
+        return self._checked(
+            self._http.put(self._url(entity, endpoint), json=wrap(record))
+        ).json()
+
+    # -- CustomizationApi (same cookie session; works on a virgin tenant) --
+
+    @staticmethod
+    def _checked_log(r: httpx.Response) -> dict[str, Any]:
+        """Raise on in-band CustomizationApi errors (verified vs 26.101.0225).
+
+        The CustomizationApi answers 200 even when an operation fails — the
+        failure only shows as ``log`` entries with ``logType: "error"``
+        (e.g. an import that rejects the package still returns 200).
+        """
+        AcumaticaClient._checked(r)
+        try:
+            body: dict[str, Any] = r.json()
+        except ValueError:
+            return {}
+        log = body.get("log")
+        errors = [
+            str(entry.get("message", ""))
+            for entry in (log if isinstance(log, list) else [])
+            if isinstance(entry, dict) and entry.get("logType") == "error"
+        ]
+        if errors:
+            raise RuntimeError(
+                f"POST {r.request.url.path} reported: " + "; ".join(errors)
+            )
+        return body
+
+    def customization_published(self) -> list[str]:
+        """Names of the customization projects published in the session tenant."""
+        body = self._checked_log(
+            self._http.post("/CustomizationApi/getPublished", json={})
+        )
+        projects = body.get("projects") or []
+        return [p["name"] for p in projects if isinstance(p, dict) and "name" in p]
+
+    def customization_project_exists(self, name: str) -> bool:
+        """True when the project's content rows exist in the session tenant.
+
+        getPublished alone is a false idempotence proxy: a tenant deleted and
+        recreated under the same CompanyID still LISTS the publication while
+        the project content (and everything the publish wrote) is gone
+        (verified live vs 26.101.0225).
+        """
+        try:
+            body = self._checked_log(
+                self._http.post(
+                    "/CustomizationApi/getProject", json={"projectName": name}
+                )
+            )
+        except RuntimeError:
+            return False
+        return bool(body.get("projectContentBase64"))
+
+    def customization_import(
+        self, name: str, zip_bytes: bytes, description: str = ""
+    ) -> None:
+        """Upload a customization package zip (replacing any same-name project).
+
+        The content field is ``projectContentBase64`` — the live binder's
+        property (ImportParamsData, verified vs 26.101.0225 by reflection).
+        The widely documented ``projectContents`` binds nothing on this
+        build: the server deletes the existing project (isReplaceIfExists)
+        and then reports "The project is not found".
+        """
+        self._checked_log(
+            self._http.post(
+                "/CustomizationApi/import",
+                json={
+                    "projectLevel": 0,
+                    "isReplaceIfExists": True,
+                    "projectName": name,
+                    "projectDescription": description,
+                    "projectContentBase64": base64.b64encode(zip_bytes).decode("ascii"),
+                },
+            )
+        )
+
+    def customization_publish_begin(self, names: list[str]) -> None:
+        """Start publishing the named projects into the current tenant."""
+        self._checked_log(
+            self._http.post(
+                "/CustomizationApi/publishBegin",
+                json={
+                    "isMergeWithExistingPackages": False,
+                    "isOnlyValidation": False,
+                    "isOnlyDbUpdates": False,
+                    "isReplayPreviouslyExecutedScripts": False,
+                    "projectNames": names,
+                    "tenantMode": "Current",
+                },
+            )
+        )
+
+    def customization_publish_end(self) -> dict[str, Any]:
+        """Poll the running publish: {isCompleted, isFailed, log: [...]}."""
+        return self._checked(
+            self._http.post("/CustomizationApi/publishEnd", json={})
+        ).json()

acumatica_cli/config.py

@@ -0,0 +1,113 @@
+"""The instance target (acu.yaml, found by walking up from cwd) + credentials (.env).
+
+Layered defaults: ``host`` is the only required acu.yaml key. Everything else
+is a code default transcribed from the verified references (docs/ac-exe.md,
+docs/rest-api.md — V12), overridable per instance for nonstandard installs.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+from pydantic import ValidationError, field_validator, model_validator
+
+from .models import Model, validation_summary
+
+
+class Instance(Model):
+    """The resolved target: the acu.yaml top-level map + credentials.
+
+    ``host`` drives both planes (V1): REST ``base_url`` and control-plane
+    ``ssh`` derive from it unless the acu.yaml map overrides them
+    explicitly (split-horizon DNS, port forwards, jump hosts, nonroot sites).
+    """
+
+    host: str
+    tenant: str = ""
+    scheme: str = "http"  # docs/rest-api.md: http://acu-dev1.vm.internal/...
+    ssh_user: str = "Administrator"
+    instance_name: str = "AcumaticaERP"
+    instance_path: str = "C:\\Acumatica\\AcumaticaERP"
+    ac_exe: str = "C:\\Program Files\\Acumatica ERP\\Data\\ac.exe"
+    db_name: str = "AcumaticaDB"
+    endpoint: str = "Default/25.200.001"  # V11: versioned path only
+    base_url: str = ""  # default derived: <scheme>://<host>/<instance_name>
+    ssh: str = ""  # default derived: <ssh_user>@<host>
+    username: str
+    password: str
+
+    @field_validator("base_url")
+    @classmethod
+    def _no_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+
+    @field_validator("endpoint")
+    @classmethod
+    def _no_surrounding_slashes(cls, v: str) -> str:
+        return v.strip("/")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _derive_urls(cls, data: Any) -> Any:
+        """Construct base_url/ssh from host; an explicit override wins."""
+        if not isinstance(data, dict) or not data.get("host"):
+            return data  # let field validation report the missing host
+
+        def resolved(key: str) -> object:
+            return data.get(key) or cls.model_fields[key].default
+
+        data = dict(data)
+        host = data["host"]
+        if not data.get("base_url"):
+            data["base_url"] = (
+                f"{resolved('scheme')}://{host}/{resolved('instance_name')}"
+            )
+        if not data.get("ssh"):
+            data["ssh"] = f"{resolved('ssh_user')}@{host}"
+        return data
+
+
+def data_root() -> Path:
+    """Walk up from cwd to the first directory containing acu.yaml."""
+    for d in [Path.cwd(), *Path.cwd().parents]:
+        if (d / "acu.yaml").is_file():
+            return d
+    raise SystemExit(
+        "acu.yaml not found in the current directory or any parent - "
+        "run acu from inside a data repo (e.g. acumatica-baseline)"
+    )
+
+
+def load_instance(host: str | None = None) -> Instance:
+    """Resolve the target from acu.yaml and merge credentials from .env/environment.
+
+    ``host`` (the global --host flag) replaces the acu.yaml host before the
+    Instance is built, so derived base_url/ssh follow it; a post-hoc
+    model_copy would leave them pointing at the old host. Explicit acu.yaml
+    base_url/ssh overrides still win, exactly as they do over the file's own
+    host.
+    """
+    root = data_root()
+    load_dotenv(root / ".env")
+
+    with open(root / "acu.yaml") as f:
+        config = yaml.safe_load(f)
+    if not isinstance(config, dict):
+        raise SystemExit("acu.yaml: expected a mapping (host + optional overrides)")
+    if host is not None:
+        config["host"] = host
+
+    password = os.environ.get("ACU_PASSWORD")
+    if not password:
+        raise SystemExit("ACU_PASSWORD not set (put it in .env or the environment)")
+
+    try:
+        return Instance(
+            username=os.environ.get("ACU_USER", "admin"),
+            password=password,
+            **config,
+        )
+    except ValidationError as exc:
+        raise SystemExit(f"acu.yaml: {validation_summary(exc)}") from exc

acumatica_cli/firstlogin.py

@@ -0,0 +1,171 @@
+"""First-login admin password initialization via the Login.aspx screen flow.
+
+A freshly created tenant seeds ``admin``/``setup`` with a
+must-change-on-first-login flag the contract REST API cannot clear (verified —
+see docs/rest-api.md). The sign-in screen's WebForms flow can, with plain
+HTTP: GET the page for the hidden fields, POST the seed credentials, then
+POST again with the new password into the change view the server renders.
+"""
+
+import time
+from contextlib import suppress
+from html.parser import HTMLParser
+
+import httpx
+
+from .config import Instance
+
+LOGIN_PATH = "/Frames/Login.aspx"
+SEED_PASSWORD = "setup"  # what a new tenant's admin is born with
+
+TENANT_FIELD = "ctl00$phUser$cmbCompany"
+USER_FIELD = "ctl00$phUser$txtUser"
+PASS_FIELD = "ctl00$phUser$txtPass"
+NEW_PASS_FIELD = "ctl00$phUser$txtNewPassword"
+CONFIRM_PASS_FIELD = "ctl00$phUser$txtConfirmPassword"
+# The page has four submit inputs; this is the right one (mfLoginButton is the
+# multi-factor flow). Both new-password fields must be posted together.
+LOGIN_BUTTON = "ctl00$phUser$btnLogin"
+REMEMBER_FIELD = "ctl00$phUser$rememberDevice"
+
+
+class _LoginForm(HTMLParser):
+    """Collects the sign-in form's postable fields (inputs and selects)."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.fields: dict[str, str] = {}
+        self._select: str | None = None
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        a = dict(attrs)
+        name = a.get("name")
+        if tag == "input" and name:
+            itype = (a.get("type") or "text").lower()
+            if itype in ("submit", "button"):
+                return  # buttons are posted explicitly by the caller
+            if itype == "checkbox" and "checked" not in a:
+                return
+            self.fields[name] = a.get("value") or ""
+        elif tag == "select" and name:
+            self._select = name
+            self.fields[name] = ""
+        elif tag == "option" and self._select and "selected" in a:
+            self.fields[self._select] = a.get("value") or ""
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "select":
+            self._select = None
+
+
+def _form_fields(html: str) -> dict[str, str]:
+    parser = _LoginForm()
+    parser.feed(html)
+    return parser.fields
+
+
+def _rest_login_works(instance: Instance, tenant: str) -> bool:
+    """One REST login attempt with the instance credentials (then logout)."""
+    with httpx.Client(base_url=instance.base_url, timeout=60) as http:
+        r = http.post(
+            "/entity/auth/login",
+            json={
+                "name": instance.username,
+                "password": instance.password,
+                "tenant": tenant,
+            },
+        )
+        if r.status_code == 204:
+            http.post("/entity/auth/logout", content=b"")
+            return True
+    return False
+
+
+def _get_login_page(http: httpx.Client, retries: int, delay: float) -> httpx.Response:
+    """GET the sign-in page, retrying while the app warms up after a recycle."""
+    last = ""
+    for attempt in range(retries):
+        try:
+            r = http.get(LOGIN_PATH)
+            if r.status_code == 200:
+                return r
+            last = f"HTTP {r.status_code}"
+        except httpx.TransportError as e:
+            last = repr(e)
+        if attempt < retries - 1:
+            time.sleep(delay)
+    raise RuntimeError(f"sign-in page did not come back after recycle: {last}")
+
+
+def initialize_admin_password(
+    instance: Instance, tenant: str, retries: int = 24, delay: float = 5.0
+) -> str:
+    """Change the tenant's seeded admin password to the instance password.
+
+    Returns ``"already initialized"`` if REST login already works (the normal
+    case — ``acu tenant create`` presets the password via ac.exe), or
+    ``"password changed"`` after a successful screen-flow change (verified by
+    a REST login). Raises RuntimeError when neither path succeeds.
+    """
+    with httpx.Client(
+        base_url=instance.base_url,
+        timeout=httpx.Timeout(10.0, read=300.0),
+        follow_redirects=True,
+    ) as http:
+        # fetch the page first: it doubles as the wait for the app to warm up
+        # after the post-create app-pool recycle
+        page = _get_login_page(http, retries, delay)
+        if _rest_login_works(instance, tenant):
+            return "already initialized"
+
+        fields = _form_fields(page.text)
+        fields.pop(REMEMBER_FIELD, None)
+        fields.update(
+            {
+                TENANT_FIELD: tenant,
+                USER_FIELD: instance.username,
+                PASS_FIELD: SEED_PASSWORD,
+                LOGIN_BUTTON: "Sign In",
+            }
+        )
+        page = http.post(LOGIN_PATH, data=fields)
+
+        fields = _form_fields(page.text)
+        if NEW_PASS_FIELD not in fields:
+            state = (
+                "seed password signed straight in - no change demanded; "
+                "the admin password is still the seed"
+                if "Main" in page.url.path
+                else f"landed on {page.url}"
+            )
+            raise RuntimeError(
+                f"tenant {tenant!r}: expected the password-change view after "
+                f"signing in with the seed password; {state}"
+            )
+        fields.pop(REMEMBER_FIELD, None)
+        fields.update(
+            {
+                TENANT_FIELD: tenant,
+                USER_FIELD: instance.username,
+                PASS_FIELD: SEED_PASSWORD,
+                NEW_PASS_FIELD: instance.password,
+                CONFIRM_PASS_FIELD: instance.password,
+                LOGIN_BUTTON: "Sign In",
+            }
+        )
+        page = http.post(LOGIN_PATH, data=fields)
+        with suppress(httpx.HTTPError):
+            # the screen session holds a license seat — best-effort logout
+            http.post("/entity/auth/logout", content=b"")
+        if "Main" not in page.url.path:
+            raise RuntimeError(
+                f"tenant {tenant!r}: password change not accepted "
+                f"(landed on {page.url})"
+            )
+
+    if not _rest_login_works(instance, tenant):
+        raise RuntimeError(
+            f"tenant {tenant!r}: password change looked accepted but REST "
+            "login with the new password failed"
+        )
+    return "password changed"

acumatica_cli/models.py

@@ -0,0 +1,21 @@
+"""pydantic is the repo's model standard.
+
+Every structured value crossing a boundary (acu.yaml maps, baseline YAML,
+sqlcmd rows) is a frozen pydantic model validated at parse time — unknown
+fields are rejected, not silently carried.
+"""
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+
+class Model(BaseModel):
+    """Base for all acu models: immutable, unknown fields are errors."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+def validation_summary(exc: ValidationError) -> str:
+    """One line per error: dotted field path + pydantic's message."""
+    return "; ".join(
+        f"{'.'.join(str(p) for p in err['loc'])}: {err['msg']}" for err in exc.errors()
+    )

acumatica_cli/output.py

@@ -0,0 +1,70 @@
+"""CLI output helpers — the only place `acu` writes to the terminal.
+
+Two audiences, one code path (SPEC V9): rich renders color, tables,
+and spinners on a TTY and degrades to plain deterministic text when piped
+(how LLM agents and scripts see it). stdout carries data and results;
+stderr carries status, warnings, and errors.
+"""
+
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+
+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 data(msg: str) -> None:
+    """Result line on stdout — what a script or agent consumes."""
+    # soft_wrap: a result line must stay one greppable line, never
+    # hard-wrapped at console width (long paths, drift lines)
+    out.print(msg, soft_wrap=True)
+
+
+def info(msg: str) -> None:
+    """Progress line on stderr."""
+    err.print(msg, style="dim cyan")
+
+
+def success(msg: str) -> None:
+    """Success line on stderr."""
+    err.print(f"+ {msg}", style="green")
+
+
+def warn(msg: str) -> None:
+    """Warning line on stderr."""
+    err.print(f"! {msg}", style="yellow")
+
+
+def error(msg: str) -> None:
+    """Error line on stderr."""
+    err.print(f"x {msg}", style="red")
+
+
+def table(title: str, columns: Iterable[str], rows: Iterable[Iterable[str]]) -> None:
+    """Table on stdout: ASCII box on a TTY, plain aligned columns piped."""
+    t = Table(
+        title=title,
+        title_justify="left",
+        box=box.ASCII if out.is_terminal else None,
+    )
+    for column in columns:
+        t.add_column(column)
+    for row in rows:
+        t.add_row(*row)
+    out.print(t)
+
+
+@contextmanager
+def step(msg: str) -> Generator[None]:
+    """Long operation: spinner on a TTY, plain stderr line when piped."""
+    if err.is_terminal:
+        # "line" is the ASCII spinner (-\|/); the default "dots" is braille
+        with err.status(msg, spinner="line"):
+            yield
+    else:
+        info(msg)
+        yield