acumatica-cli 0.2.2__tar.gz

acumatica_cli-0.2.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,172 @@
+# 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/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "acumatica-cli"
+version = "0.2.2"
+description = "The acu CLI - Acumatica ERP configuration as code: tenant provisioning, baseline config, and reference data"
+authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "python-dotenv>=1.0",
+    "pyyaml>=6.0",
+    "rich>=13",
+]
+
+[project.scripts]
+acu = "acumatica_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.37.0",
+    "pytest>=8",
+    "ruff>=0.13.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = '-q -m "not e2e"'
+markers = [
+    "e2e: live end-to-end tests against a real Acumatica instance (make e2e)",
+]
+
+[tool.basedpyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+include = ["src/acumatica_cli/", "tests/"]
+reportMissingTypeStubs = false
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportUnknownLambdaType = false
+reportUnusedFunction = "warning"
+
+[tool.ruff]
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = [
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "C90",   # mccabe
+    "COM",   # flake8-commas
+    "D",     # pydocstyle
+    "E",     # pycodestyle
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "PL",    # Pylint
+    "PT",    # flake8-pytest-style
+    "RUF",   # Ruff-specific rules
+    "SIM",   # flake8-simplify
+    "T20",   # flake8-print: no bare print(); use acumatica_cli.output
+    "TID",   # flake8-tidy-imports
+    "UP",    # pyupgrade
+    "W",     # pycodestyle warnings
+]
+ignore = [
+    "PLR2004",  # magic values in comparisons
+    "PLC0415",  # import not at top-level (lazy imports)
+    "D100",     # Missing docstring in public module
+    "D104",     # Missing docstring in public package
+    "D105",     # Missing docstring in magic method
+    "D107",     # Missing docstring in __init__
+    "COM812",   # trailing commas
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["acumatica_cli"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/acumatica_cli/cli.py" = [
+    "PLR0913", # Click commands have many parameters by design
+]
+"tests/*" = [
+    "D101", # test classes/functions are named descriptively instead
+    "D102",
+    "D103",
+]

acumatica_cli-0.2.2/src/acumatica_cli/bootstrap.py

@@ -0,0 +1,105 @@
+"""Bootstrap customization package: build the zip, publish via /CustomizationApi.
+
+An unconfigured tenant cannot be configured through the Default endpoint
+(features are off, no company/branch exists, credit terms have no entity —
+docs/rest-api.md). The CustomizationApi is the one door that works on a
+virgin tenant, so bootstrap = publish a package whose CustomizationPlugin
+(`bootstrap_plugin.cs`) enables features on publish — the contract API
+cannot write CS100000 at all (T3 verdict) — and whose Bootstrap contract
+endpoint exposes CS101500 company + CS206500 credit terms for seeding
+(`bootstrap_project.xml`, serialization verified T12).
+
+Customization publishes are tenant-scoped, so the package must be published
+per tenant; publish() is idempotent — an already-published package is a
+no-op skip, and the plugin's UpdateDatabase is a keyed update on re-run.
+"""
+
+import io
+import time
+import xml.etree.ElementTree as ET
+import zipfile
+from importlib import resources
+
+import httpx
+
+from .client import AcumaticaClient
+
+# Alphanumeric only: CstDbStorage.ValidatePackageName rejects '-' and '_'
+# (verified vs 26.101.0225 — "Invalid project name")
+PACKAGE_NAME = "AcuBootstrap"
+PACKAGE_DESCRIPTION = (
+    "acu bootstrap: CustomizationPlugin enables features on publish; "
+    "Bootstrap endpoint exposes company + credit terms"
+)
+PLUGIN_CLASS = "AcuBootstrapPlugin"
+
+
+def package_zip() -> bytes:
+    """Build the customization package: a zip holding project.xml.
+
+    The C# plugin travels as a <Graph> item whose Source ATTRIBUTE holds the
+    file content (Customization.CstCodeFile shape, verified vs 26.101.0225:
+    inline CDATA and zip-file variants are silently dropped on import).
+    ElementTree escapes the newlines as &#10; on serialization.
+    """
+    pkg = resources.files("acumatica_cli")
+    root = ET.fromstring((pkg / "bootstrap_project.xml").read_bytes())
+    graph = ET.SubElement(root, "Graph")
+    graph.set("ClassName", PLUGIN_CLASS)
+    graph.set("FileType", "NewFile")
+    graph.set("Source", (pkg / "bootstrap_plugin.cs").read_text(encoding="utf-8"))
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("project.xml", ET.tostring(root, encoding="utf-8"))
+    return buf.getvalue()
+
+
+def _log_tail(status: dict[str, object], limit: int = 5) -> str:
+    """Last few publish-log messages, for a one-line error (SPEC V9)."""
+    log = status.get("log")
+    if not isinstance(log, list):
+        return ""
+    messages = [
+        str(entry.get("message", "")) for entry in log if isinstance(entry, dict)
+    ]
+    return "; ".join(m for m in messages[-limit:] if m)
+
+
+def publish(client: AcumaticaClient, timeout: float = 600.0, poll: float = 5.0) -> str:
+    """Publish the bootstrap package into the client's session tenant.
+
+    Idempotent: returns ``"already published"`` when getPublished lists the
+    package AND its content still exists (a recreated tenant with the same
+    CompanyID keeps the stale publication row while the content and the
+    plugin's writes are gone), else import -> publishBegin -> poll publishEnd
+    until the server reports completion. Transport errors while polling are
+    tolerated — publishing restarts the app domain, so the site may briefly
+    drop connections mid-publish. Raises RuntimeError on a failed publish or
+    on timeout.
+    """
+    if PACKAGE_NAME in client.customization_published() and (
+        client.customization_project_exists(PACKAGE_NAME)
+    ):
+        return "already published"
+    client.customization_import(
+        PACKAGE_NAME, package_zip(), description=PACKAGE_DESCRIPTION
+    )
+    client.customization_publish_begin([PACKAGE_NAME])
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            status = client.customization_publish_end()
+        except httpx.TransportError:
+            status = {}  # site restarting mid-publish; keep polling
+        if status.get("isFailed"):
+            detail = _log_tail(status)
+            raise RuntimeError(
+                f"publishing {PACKAGE_NAME} failed" + (f": {detail}" if detail else "")
+            )
+        if status.get("isCompleted"):
+            return "published"
+        if time.monotonic() >= deadline:
+            raise RuntimeError(
+                f"publishing {PACKAGE_NAME} did not complete within {timeout:.0f}s"
+            )
+        time.sleep(poll)

acumatica_cli-0.2.2/src/acumatica_cli/bootstrap_plugin.cs

@@ -0,0 +1,62 @@
+// acu bootstrap CustomizationPlugin (SPEC T11).
+//
+// Runs in-process on customization publish - the one write path to
+// FeaturesSet that works: the contract API cannot persist features no
+// matter what endpoint fronts CS100000 (T3 verdict, docs/rest-api.md).
+//
+// Deliberately writes through PXDatabase, not FeaturesMaint: the graph
+// save collides with the publish pipeline's concurrent plugin invocations
+// ("Another process has added the 'FeaturesSet' record" - observed live,
+// 26.101.0225) and nothing persists. A keyed row write is deterministic
+// and idempotent: update the existing row, insert when absent. All 205
+// NOT NULL bit columns are filled reflectively (only ~136 carry DB
+// defaults); Status = 0 means Validated (PXIntList, verified vs live).
+using System.Collections.Generic;
+using System.Reflection;
+using PX.Data;
+using PX.Objects.CS;
+
+namespace AcuBootstrap
+{
+    public class AcuBootstrapPlugin : Customization.CustomizationPlugin
+    {
+        private static readonly HashSet<string> Enabled = new HashSet<string>
+        {
+            "FinancialModule",
+            "FinancialStandard",
+            "DistributionModule",
+            "Inventory",
+            "Branch",
+            "MultiCompany",
+        };
+
+        public override void UpdateDatabase()
+        {
+            var flags = new List<PXDataFieldAssign>();
+            foreach (PropertyInfo prop in typeof(FeaturesSet).GetProperties())
+            {
+                if (prop.PropertyType == typeof(bool?))
+                {
+                    flags.Add(new PXDataFieldAssign(
+                        prop.Name, PXDbType.Bit, Enabled.Contains(prop.Name)));
+                }
+            }
+            flags.Add(new PXDataFieldAssign("Status", PXDbType.Int, 0)); // Validated
+
+            using (var tx = new PXTransactionScope())
+            {
+                bool updated = PXDatabase.Update<FeaturesSet>(flags.ToArray());
+                if (!updated)
+                {
+                    PXDatabase.Insert<FeaturesSet>(flags.ToArray());
+                    WriteLog("AcuBootstrap: FeaturesSet row inserted (features enabled)");
+                }
+                else
+                {
+                    WriteLog("AcuBootstrap: FeaturesSet row updated (features enabled)");
+                }
+                tx.Complete();
+            }
+        }
+    }
+}