acumatica-cli 0.2.2__py3-none-any.whl

acumatica_cli/seed.py

@@ -0,0 +1,120 @@
+"""Reference data as code: baseline/*.yaml applied to the live tenant.
+
+apply = entity PUTs (upsert by key); diff = live-vs-source comparison
+(the drift proof).
+
+Baseline file format:
+
+    entity: Currency          # entity name in the contract endpoint
+    key: CurrencyID           # key field(s), string or list
+    endpoint: Bootstrap/1.0.0 # optional: override the instance endpoint
+    records:
+      - CurrencyID: "CAD"
+        Description: Canadian Dollar
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import Field, ValidationError, field_validator, model_validator
+
+from . import output
+from .client import AcumaticaClient, unwrap
+from .models import Model, validation_summary
+
+
+class BaselineFile(Model):
+    """A parsed baseline YAML: one entity, its key fields, its records."""
+
+    path: Path
+    entity: str
+    keys: list[str] = Field(alias="key")
+    records: list[dict[str, Any]]
+    endpoint: str | None = None  # bootstrap YAML targets the custom endpoint
+
+    @field_validator("keys", mode="before")
+    @classmethod
+    def _key_as_list(cls, v: object) -> object:
+        return v if isinstance(v, list) else [v]
+
+    @model_validator(mode="after")
+    def _records_carry_keys(self) -> "BaselineFile":
+        for i, record in enumerate(self.records):
+            for k in self.keys:
+                if k not in record:
+                    raise ValueError(f"records[{i}] missing key field '{k}'")
+        return self
+
+
+def load_baseline(path: Path) -> BaselineFile:
+    """Parse and validate one baseline 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 BaselineFile.model_validate({"path": path, **data})
+    except ValidationError as exc:
+        raise SystemExit(f"{path}: {validation_summary(exc)}") from exc
+
+
+def _norm(value: Any) -> str:
+    """Comparable form: bools case-folded, numbers by value, rest stringified.
+
+    Numbers compare by value, not spelling - a YAML `0` against the
+    endpoint's `0.0` (DecimalValue fields come back as floats) is not
+    drift (T13).
+    """
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, int | float):
+        return repr(float(value))
+    return str(value).strip()
+
+
+def _filter_for(record: dict[str, Any], keys: list[str]) -> str:
+    return " and ".join(f"{k} eq '{record[k]}'" for k in keys)
+
+
+def apply(
+    client: AcumaticaClient, baseline: BaselineFile, dry_run: bool = False
+) -> int:
+    """PUT every record (upsert by key). Returns the record count."""
+    for record in baseline.records:
+        label = ", ".join(str(record[k]) for k in baseline.keys)
+        if dry_run:
+            output.data(f"  would PUT {baseline.entity} [{label}]")
+        else:
+            client.put(baseline.entity, record, endpoint=baseline.endpoint)
+            output.data(f"  PUT {baseline.entity} [{label}]")
+    return len(baseline.records)
+
+
+def diff(client: AcumaticaClient, baseline: BaselineFile) -> list[str]:
+    """Compare each source record against the live tenant.
+
+    Returns human-readable drift lines (empty = no drift).
+    """
+    drifts: list[str] = []
+    for record in baseline.records:
+        label = (
+            f"{baseline.entity} [{', '.join(str(record[k]) for k in baseline.keys)}]"
+        )
+        live = client.get_list(
+            baseline.entity,
+            params={"$filter": _filter_for(record, baseline.keys)},
+            endpoint=baseline.endpoint,
+        )
+        if not live:
+            drifts.append(f"{label}: missing on tenant")
+            continue
+        actual = unwrap(live[0])
+        for field, expected in record.items():
+            if field not in actual:
+                drifts.append(f"{label}.{field}: not returned by endpoint")
+            elif _norm(actual[field]) != _norm(expected):
+                drifts.append(
+                    f"{label}.{field}: source={expected!r} live={actual[field]!r}"
+                )
+    return drifts

acumatica_cli/tenant.py

@@ -0,0 +1,149 @@
+"""Tenant CRUD on the instance.
+
+Thin SSH wrapper around ac.exe CompanyConfig (the only supported CLI route,
+see docs/ac-exe.md) plus a sqlcmd read side.
+"""
+
+import subprocess
+
+from .config import Instance
+from .models import Model
+
+
+class Tenant(Model):
+    """One row of the instance's Company table.
+
+    login_name is dbo.Company.CompanyKey — the name on the sign-in page and
+    the REST login's tenant value. company_cd is the internal auto-generated
+    code (ac.exe ignores LoginName for it; see docs/ac-exe.md).
+    """
+
+    company_id: int
+    company_cd: str
+    login_name: str
+    company_type: str
+
+
+class TenantManager:
+    """Tenant CRUD via SSH to the Windows guest."""
+
+    def __init__(self, instance: Instance):
+        self.instance = instance
+
+    def _ssh(self, command: str) -> str:
+        # PowerShell-over-ssh returns 0 even when the native command fails;
+        # appending the exit here (single choke point, never at call sites)
+        # makes every remote failure propagate (SPEC V18, B4).
+        r = subprocess.run(
+            [
+                "ssh",
+                "-o",
+                "BatchMode=yes",
+                self.instance.ssh,
+                command + "\nexit $LASTEXITCODE",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if r.returncode != 0:
+            raise RuntimeError(
+                f"remote command failed ({r.returncode}):\n{r.stdout}\n{r.stderr}"
+            )
+        return r.stdout
+
+    def list(self) -> list[Tenant]:
+        """Read tenants from the Company table (sqlcmd over SSH)."""
+        query = (
+            "SET NOCOUNT ON; "
+            "SELECT CompanyID, CompanyCD, ISNULL(CompanyKey, ''), CompanyType "
+            f"FROM {self.instance.db_name}.dbo.Company ORDER BY CompanyID"
+        )
+        out = self._ssh(f'sqlcmd -S "(local)" -E -C -W -h -1 -s "|" -Q "{query}"')
+        tenants = []
+        for line in out.splitlines():
+            parts = [p.strip() for p in line.split("|")]
+            if len(parts) == 4 and parts[0].isdigit():
+                tenants.append(
+                    Tenant(
+                        company_id=int(parts[0]),
+                        company_cd=parts[1],
+                        login_name=parts[2],
+                        company_type=parts[3],
+                    )
+                )
+        return tenants
+
+    def recycle_app_pool(self) -> None:
+        """Recycle the IIS app pool so the running app reloads its tenant map.
+
+        The tenant map loads at app start; without this, tenants created or
+        deleted by CompanyConfig stay invisible to the sign-in page and REST
+        routing silently falls back to the default tenant (docs/rest-api.md).
+        The pool is named after the instance (how acumatica-infra builds it).
+        """
+        self._ssh(
+            "Import-Module WebAdministration; "
+            f"Restart-WebAppPool -Name '{self.instance.instance_name}'"
+        )
+
+    def _company_config(self, company: str, extra: str = "") -> str:
+        # -iname AND -h are both required: without -iname CompanyConfig can't
+        # find the site; without -h its web.config step dies on a null path
+        # (verified 2026-07-08, docs/ac-exe.md).
+        return self._ssh(
+            f"& '{self.instance.ac_exe}' "
+            f'-configmode:"CompanyConfig" -output:"Forced" '
+            f'-iname:"{self.instance.instance_name}" '
+            f'-h:"{self.instance.instance_path}" '
+            f'-dbsrvname:"(local)" -dbsrvwinauth:"True" '
+            f'-dbname:"{self.instance.db_name}" -dbnew:"False" '
+            f'-company:"{company}"{extra}'
+        )
+
+    def create(
+        self,
+        company_id: int,
+        login_name: str,
+        parent_id: int = 1,
+        visible: bool = True,
+        company_type: str = "",
+    ) -> str:
+        """Create (or, for an existing CompanyID, overwrite!) a tenant.
+
+        company_type: '' = clean tenant, 'SalesDemo' = demo data. The admin
+        flags preset the tenant's admin to the instance credentials with no
+        must-change flag, so the tenant is REST-loginable right after the
+        app-pool recycle — no first-login dance (verified, docs/ac-exe.md).
+        """
+        company = (
+            f"CompanyID={company_id};ParentID={parent_id};"
+            f"Visible={'Yes' if visible else 'No'};"
+            f"CompanyType={company_type};LoginName={login_name};"
+        )
+        admin = (
+            f' -aun:"{self.instance.username}" '
+            f'-aup:"{self.instance.password}" -auc:"False"'
+        )
+        return self._company_config(company, extra=admin)
+
+    def delete(self, company_id: int) -> str:
+        """Delete the tenant and all its data.
+
+        Two verified gotchas (docs/ac-exe.md):
+
+        - The sub-key is ``Deleted``, not the officially documented
+          ``Delete`` — an unknown key is silently ignored and the run degrades
+          into a *destructive data re-insert* into the tenant.
+        - The full spec (``ParentID`` + ``CompanyType``) must be passed. With
+          only ``CompanyID;Deleted=Yes`` the preflight reads an empty
+          CompanyType as the system tenant and aborts with "The system company
+          cannot be removed."
+        """
+        target = next((t for t in self.list() if t.company_id == company_id), None)
+        if target is None:
+            raise RuntimeError(f"no tenant with CompanyID={company_id}")
+        return self._company_config(
+            f"CompanyID={company_id};ParentID=1;"
+            f"CompanyType={target.company_type};Deleted=Yes;"
+        )

acumatica_cli-0.2.2.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: acumatica-cli
+Version: 0.2.2
+Summary: The acu CLI - Acumatica ERP configuration as code: tenant provisioning, baseline config, and reference data
+Author: Konstantin Borovik
+Author-email: Konstantin Borovik <kb@lab5.ca>
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Acumatica CLI
+
+**`acu`** — configure Acumatica ERP purely from source code: no UI clicks,
+no Configuration Wizard.
+
+Every operation is idempotent:
+
+- `acu apply` upserts records by key — running it twice is safe
+- `acu diff` detects drift between your YAML and the live tenant
+- `acu provision` takes an empty instance to a fully configured tenant in
+  one command, and skips every step that is already done
+
+## Why?
+
+Acumatica configuration normally lives in the web UI: wizards, screens, and
+manual data entry that nobody can review, version, or reproduce. `acu` moves
+that configuration into YAML files in a git repo, so a tenant can be rebuilt
+from scratch, audited in a pull request, and checked for drift like any other
+infrastructure.
+
+## Quick start
+
+From the data repo:
+
+```sh
+acu config show     # sanity-check the resolved target
+```
+
+```sh
+acu provision --id 3 --login DEV        # create → bootstrap → apply → diff
+acu diff baseline/                      # later: prove zero drift (exit 2 on drift)
+```
+
+## CLI Map
+
+```text
+acu [-t TENANT]
+│
+├── provision --id N --login NAME     one command: create → bootstrap → apply → diff
+│             [--type SalesDemo] [--parent N]
+│
+├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
+│   ├── list                          CompanyID, sign-in name, internal CD, type
+│   ├── create                        create a tenant and make it automation-ready
+│   └── delete                        delete a tenant and its data, recycle app pool
+│
+├── apply [--dry-run] FILES...        seed baseline YAML via REST (idempotent PUT upserts)
+├── diff FILES...                     drift check: YAML vs live tenant (exit 2 on drift)
+├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
+│
+└── config                            local, read-only — never talks to a live instance
+    └── show                          print the resolved target as a complete acu.yaml
+```
+
+The target instance comes from `acu.yaml` (found by walking up from the
+current directory); the one global option `-t/--tenant` overrides the tenant
+that API sessions sign in to. Run `acu <command> --help` for details on any
+command.
+
+## Installation
+
+## Configuration
+
+Configuration is split into three layers, each answering one question:
+
+1. **`acu.yaml`** — *where* to apply. The whole file is the target
+   instance: a flat map where `host` is the only required key; everything
+   else has a code default matching a stock Acumatica install:
+
+   ```yaml
+   host: acu-dev1.vm.internal
+   tenant: Company     # sign-in name of the tenant API sessions use
+   ```
+
+   Optional overrides (defaults shown) for nonstandard installs,
+   split-horizon DNS, port forwards, or jump hosts:
+
+   `acu config show` prints the fully resolved instance as a complete,
+   valid `acu.yaml` — every knob visible, credentials excluded. To turn
+   the resolved state into your working config, redirect and edit:
+
+   ```sh
+   acu config show > acu.yaml
+   ```
+
+2. **`.env`** — *who* signs in to the REST API. Loaded from the data-repo
+   root (or the plain environment):
+
+   ```sh
+   ACU_PASSWORD=...    # required
+   ACU_USER=admin      # optional, defaults to admin
+   ```
+
+   The data repo stores it encrypted as `.env.gpg`; `make decrypt` produces
+   the plaintext `.env` once per clone.
+
+3. **SSH** — *how* the control plane reaches the Windows guest. Configured on
+   the guest and in your `~/.ssh`, not in `acu.yaml` — see the next section.
+
+Verify the result before touching anything live:
+
+```sh
+acu config show           # the fully resolved instance as acu.yaml, no secrets
+acu apply --dry-run baseline/
+```
+
+## Two planes
+
+`acu` talks to an instance over two independent channels:
+
+- **Control plane (SSH):** tenant create/delete/list via `ac.exe
+  -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see
+  [`docs/ac-exe.md`](docs/ac-exe.md). Used by `acu tenant` and the first step
+  of `acu provision`.
+- **Data plane (REST):** baseline configuration and reference data through
+  the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a
+  keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md). Used by
+  `acu apply`, `acu diff`, and `acu schema`.
+
+If you only apply and diff baseline YAML, you never need SSH. SSH setup is
+required only for `acu tenant` and `acu provision`.
+
+## SSH setup (control plane)
+
+`acu tenant` and `acu provision` run commands on the Windows guest through
+plain `ssh`. Two things about this setup are not obvious, and both are hard
+requirements:
+
+**1. The default SSH shell on the Windows guest must be PowerShell.**
+`acu` sends PowerShell syntax over the wire (`& 'C:\...\ac.exe' ...`,
+`Import-Module WebAdministration`, `exit $LASTEXITCODE`). Windows OpenSSH
+ships with `cmd.exe` as the default shell, where every one of those commands
+fails. Switch it once, in an elevated PowerShell on the guest:
+
+```powershell
+New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell `
+  -Value "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
+  -PropertyType String -Force
+```
+
+**2. Authentication must be key-based and non-interactive.**
+`acu` connects with `BatchMode=yes`, so it will never answer a password
+prompt — without a working key the connection just fails. And because the
+default `ssh_user` is `Administrator` (an administrators-group member),
+Windows OpenSSH reads the key from the *machine-wide* file
+`C:\ProgramData\ssh\administrators_authorized_keys` — **not** from
+`~\.ssh\authorized_keys` like on Linux. On the guest:
+
+```powershell
+# install + start the server (once)
+Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+Set-Service sshd -StartupType Automatic
+Start-Service sshd
+
+# authorize your public key for administrators
+Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys Value "ssh-ed25519 AAAA... you@laptop"
+
+# the file must be readable by SYSTEM/Administrators only, or sshd ignores it
+icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F" 
+```
+
+Then verify from your workstation — this one test proves both requirements
+at once (key auth works, and the shell is PowerShell):
+
+```sh
+ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersion'
+```
+
+A version table means you are ready; a password prompt or
+`'$PSVersionTable.PSVersion' is not recognized...` means requirement 2 or 1
+(respectively) is not met yet. Host aliases, jump hosts, and ports go in your
+`~/.ssh/config` as usual, or set `ssh: user@alias` in `acu.yaml`.

acumatica_cli-0.2.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+acumatica_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+acumatica_cli/bootstrap.py,sha256=zCYRqwRLbG4bFgrrwQgxzrtVmtkaujhseKld088Nycw,4411
+acumatica_cli/bootstrap_plugin.cs,sha256=Z3DSemqPY9jmGQUe4n95pbBiRJLJJSW-OJSXULiIJm0,2358
+acumatica_cli/bootstrap_project.xml,sha256=V3WIFX-jZa6wk2uEZduhlvto0aFVHQWFyPp6K52jjC8,5842
+acumatica_cli/cli.py,sha256=ab9XOZZX9qAzg3IjpNnco9QCnciOJZQE6oaHa5GADaM,12685
+acumatica_cli/client.py,sha256=oSQq2f9AG11h0YoyJ0jNA2A9URoMknuAkKn2gGvxyt4,10095
+acumatica_cli/config.py,sha256=ZUDYYOhjTq6kel3rp4Kms_ot5vRp7C0zsZfVPnXkT44,4011
+acumatica_cli/firstlogin.py,sha256=6lW29p2IKHjMvqG7oYvGwibiq0TGZZ0yekg5muxJwrI,6320
+acumatica_cli/models.py,sha256=hwQPWtIVPt6A4pEV6bXV2sLTU5KZ7nDwIGzJ09mQyUw,701
+acumatica_cli/output.py,sha256=2cGSUiBAW0sDQkFIDyKoYOvqTCUc62CjTzixz6WVEdM,2058
+acumatica_cli/seed.py,sha256=wl04PmlKuj4Hn0kvPnpsLGEWe_abZMfAQrJg_EE4E_c,4097
+acumatica_cli/tenant.py,sha256=VIRdiWiqKb7CHcVuw1CzTCfVLcVxBj5bTMM9JyMVJrY,5624
+acumatica_cli-0.2.2.dist-info/WHEEL,sha256=CoDSoyhtC_eO_tlxRYzsTraPv1fPJRXFx91k6ISeAvA,81
+acumatica_cli-0.2.2.dist-info/entry_points.txt,sha256=0DVtG5zKps5rMtP4AuppfHvXFvh5x2WZk0y8-bR1Ohc,48
+acumatica_cli-0.2.2.dist-info/METADATA,sha256=4_-xg67y1WhShxUX8jiTh2TxCi0NmQDuNCpT8FnlARw,7194
+acumatica_cli-0.2.2.dist-info/RECORD,,

acumatica_cli-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.28
+Root-Is-Purelib: true
+Tag: py3-none-any

acumatica_cli-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+acu = acumatica_cli.cli:main
+