acumatica-cli 0.2.2__tar.gz → 0.4.0__tar.gz

acumatica_cli-0.4.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.3
+Name: acumatica-cli
+Version: 0.4.0
+Summary: Acumatica ERP Config-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: pydantic-settings>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13
+Requires-Python: >=3.12
+Project-URL: Homepage, https://lab5.ca
+Project-URL: Repository, https://github.com/kborovik/acumatica-cli
+Description-Content-Type: text/markdown
+
+# Acumatica Config-as-Code
+
+**`acu`** configures Acumatica ERP from YAML files in a git repo. 
+
+**No UI clicks, no Configuration Wizard.**
+
+## How it works
+
+1. **Read** the target Acumatica deployment and translate its configuration into 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`.
+
+Three 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.
+
+> **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.
+
+## 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
+
+```sh
+uv tool install acumatica-cli
+
+acu config init --host erp.example.com my-erp
+cd my-erp                                # edit .env: set ACU_PASSWORD
+
+acu config check                         # read-only preflight
+acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it
+acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
+acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
+```
+
+## CLI map
+
+```text
+acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
+    [--username U] [--password P]
+│
+├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
+│   ├── list                          CompanyID, sign-in name, internal CD, type
+│   ├── create --id N --login NAME    create + bootstrap; re-run to republish
+│   │          [--type SalesDemo] [--parent N] [--hidden] [--no-init]
+│   └── delete --id N [--yes]         delete the tenant and its data, recycle app pool
+│
+├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
+├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
+├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
+│
+└── config                            configuration ops
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── show                          print the resolved config as a complete .env
+    └── check                         read-only preflight: discovery, secrets, REST, SSH
+```
+
+`apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`. 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:
+
+| 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            |
+| `.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.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```sh
+uv tool install acumatica-cli
+```
+
+`pipx install acumatica-cli` and `pip install acumatica-cli` work too. For the latest development version straight from the main branch:
+
+```sh
+uv tool install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+Verify with `acu --version`.
+
+## Configuration
+
+Everything lives in one `.env` file: *where* to apply and *who* signs in. Three values are required; everything else has a code default matching a stock Acumatica install:
+
+```sh
+ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP  # required: REST root
+ACU_TENANT=LAB5                                        # sign-in name of the tenant API sessions use
+ACU_SSH=Administrator@acu-dev1.vm.internal             # required: control-plane user@host
+ACU_USER=admin                                         # optional, defaults to admin
+ACU_PASSWORD=...                                       # required
+```
+
+Worth knowing:
+
+- The file is found by walking up from the current directory, so any subdirectory of the data repo works. Without a `.env`, global flags plus the process environment supply the full configuration.
+- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the two address keys.
+- `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded. Redirect it to turn resolved state into a working config: `acu config show > .env`.
+
+Verify before touching anything live:
+
+```sh
+acu config check       # read-only preflight: discovery, secrets, REST, SSH
+acu apply --dry-run    # show what would be written, write nothing
+```
+
+## Control and Data Planes
+
+`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).
+
+If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+
+## SSH setup (control plane)
+
+`acu tenant` runs 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, and every one of those commands fails under `cmd.exe`, the Windows OpenSSH default. 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.
+Because the default 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:
+
+Install + start the server (once):
+
+```powershell
+Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+Set-Service sshd -StartupType Automatic
+Start-Service sshd
+```
+
+Authorize your public key for administrators:
+
+```powershell
+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:
+
+```powershell
+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'
+```

acumatica_cli-0.4.0/README.md

@@ -0,0 +1,171 @@
+# Acumatica Config-as-Code
+
+**`acu`** configures Acumatica ERP from YAML files in a git repo. 
+
+**No UI clicks, no Configuration Wizard.**
+
+## How it works
+
+1. **Read** the target Acumatica deployment and translate its configuration into 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`.
+
+Three 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.
+
+> **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.
+
+## 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
+
+```sh
+uv tool install acumatica-cli
+
+acu config init --host erp.example.com my-erp
+cd my-erp                                # edit .env: set ACU_PASSWORD
+
+acu config check                         # read-only preflight
+acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it
+acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
+acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
+```
+
+## CLI map
+
+```text
+acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
+    [--username U] [--password P]
+│
+├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
+│   ├── list                          CompanyID, sign-in name, internal CD, type
+│   ├── create --id N --login NAME    create + bootstrap; re-run to republish
+│   │          [--type SalesDemo] [--parent N] [--hidden] [--no-init]
+│   └── delete --id N [--yes]         delete the tenant and its data, recycle app pool
+│
+├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
+├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
+├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
+│
+└── config                            configuration ops
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── show                          print the resolved config as a complete .env
+    └── check                         read-only preflight: discovery, secrets, REST, SSH
+```
+
+`apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`. 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:
+
+| 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            |
+| `.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.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```sh
+uv tool install acumatica-cli
+```
+
+`pipx install acumatica-cli` and `pip install acumatica-cli` work too. For the latest development version straight from the main branch:
+
+```sh
+uv tool install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+Verify with `acu --version`.
+
+## Configuration
+
+Everything lives in one `.env` file: *where* to apply and *who* signs in. Three values are required; everything else has a code default matching a stock Acumatica install:
+
+```sh
+ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP  # required: REST root
+ACU_TENANT=LAB5                                        # sign-in name of the tenant API sessions use
+ACU_SSH=Administrator@acu-dev1.vm.internal             # required: control-plane user@host
+ACU_USER=admin                                         # optional, defaults to admin
+ACU_PASSWORD=...                                       # required
+```
+
+Worth knowing:
+
+- The file is found by walking up from the current directory, so any subdirectory of the data repo works. Without a `.env`, global flags plus the process environment supply the full configuration.
+- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the two address keys.
+- `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded. Redirect it to turn resolved state into a working config: `acu config show > .env`.
+
+Verify before touching anything live:
+
+```sh
+acu config check       # read-only preflight: discovery, secrets, REST, SSH
+acu apply --dry-run    # show what would be written, write nothing
+```
+
+## Control and Data Planes
+
+`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).
+
+If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+
+## SSH setup (control plane)
+
+`acu tenant` runs 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, and every one of those commands fails under `cmd.exe`, the Windows OpenSSH default. 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.
+Because the default 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:
+
+Install + start the server (once):
+
+```powershell
+Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+Set-Service sshd -StartupType Automatic
+Start-Service sshd
+```
+
+Authorize your public key for administrators:
+
+```powershell
+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:
+
+```powershell
+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'
+```

{acumatica_cli-0.2.2 → acumatica_cli-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "acumatica-cli"
-version = "0.2.2"
-description = "The acu CLI - Acumatica ERP configuration as code: tenant provisioning, baseline config, and reference data"
+version = "0.4.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"
 requires-python = ">=3.12"
@@ -9,11 +9,15 @@ dependencies = [
     "click>=8.1",
     "httpx>=0.27",
     "pydantic>=2.7",
-    "python-dotenv>=1.0",
+    "pydantic-settings>=2.5",
     "pyyaml>=6.0",
     "rich>=13",
 ]
 
+[project.urls]
+Homepage = "https://lab5.ca"
+Repository = "https://github.com/kborovik/acumatica-cli"
+
 [project.scripts]
 acu = "acumatica_cli.cli:main"
 

acumatica_cli-0.4.0/src/acumatica_cli/bootstrap.py

@@ -0,0 +1,215 @@
+"""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 + CM202000
+financial currency for seeding (`bootstrap_project.xml`, serialization
+verified T12; the Default endpoint's Currency entity is the CM201000 list
+only — B8).
+
+Customization publishes are tenant-scoped, so the package must be published
+per tenant; publish() is idempotent on content — the skip gate compares the
+digest embedded in the published package's description against the package
+built now, and the plugin's UpdateDatabase is a keyed update on re-run.
+
+The feature set the plugin enables is data, not code (V2): load_features()
+reads the data repo's bootstrap/features.yaml (absent -> the built-in six)
+and package_zip() splices it into the plugin source at build time.
+"""
+
+import hashlib
+import io
+import time
+import xml.etree.ElementTree as ET
+import zipfile
+from collections.abc import Sequence
+from importlib import resources
+from pathlib import Path
+
+import httpx
+import yaml
+
+from .client import AcumaticaClient
+
+# Alphanumeric only: CstDbStorage.ValidatePackageName rejects '-' and '_'
+# (verified vs 26.101.0225 — "Invalid project name")
+PACKAGE_NAME = "AcuBootstrap"
+# Authored once, in the template's root description attribute — read it
+# here rather than hand-syncing a second copy: the XML is digest input,
+# so a divergent XML-only edit would fire a spurious republish (V4).
+PACKAGE_DESCRIPTION = ET.fromstring(
+    (resources.files("acumatica_cli") / "bootstrap_project.xml").read_bytes()
+).get("description", "")
+PLUGIN_CLASS = "AcuBootstrapPlugin"
+
+# Code default when the data repo carries no bootstrap/features.yaml
+# (SPEC I.data) — the minimum for company/branch + baseline seeding.
+# The set is injected into the plugin source at package build; it never
+# lives in bootstrap_plugin.cs (V2: feature flags are config, not tool
+# source — B6).
+DEFAULT_FEATURES = (
+    "FinancialModule",
+    "FinancialStandard",
+    "DistributionModule",
+    "Inventory",
+    "Branch",
+    "MultiCompany",
+)
+FEATURES_SENTINEL = "/*ACU_FEATURES*/"
+
+
+def load_features(root: Path) -> list[str]:
+    """The FeaturesSet property names from <root>/bootstrap/features.yaml.
+
+    Absent file -> the built-in six (SPEC I.data). Names are validated as
+    plausible property names here (they are spliced into C# string literals);
+    whether each matches a real FeaturesSet property only the plugin can
+    tell — it logs the strays at publish time (the silent-typo guard).
+    """
+    path = root / "bootstrap" / "features.yaml"
+    if not path.is_file():
+        return list(DEFAULT_FEATURES)
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    if not isinstance(data, list) or not data:
+        raise SystemExit(
+            f"{path}: expected a non-empty list of FeaturesSet property names"
+        )
+    for name in data:
+        if not isinstance(name, str) or not (name.isascii() and name.isidentifier()):
+            raise SystemExit(f"{path}: {name!r} is not a FeaturesSet property name")
+    return list(data)
+
+
+def package_zip(features: Sequence[str] | None = None) -> 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.
+
+    ``features`` (default: the built-in six) is spliced into the plugin's
+    ``Enabled`` set at the ACU_FEATURES sentinel — the one point where the
+    data repo's feature list enters the package (V2).
+    """
+    pkg = resources.files("acumatica_cli")
+    root = ET.fromstring((pkg / "bootstrap_project.xml").read_bytes())
+    source = (pkg / "bootstrap_plugin.cs").read_text(encoding="utf-8")
+    if FEATURES_SENTINEL not in source:
+        raise RuntimeError(f"bootstrap_plugin.cs: {FEATURES_SENTINEL} sentinel missing")
+    enabled = DEFAULT_FEATURES if features is None else features
+    source = source.replace(
+        FEATURES_SENTINEL, ", ".join(f'"{name}"' for name in enabled)
+    )
+    graph = ET.SubElement(root, "Graph")
+    graph.set("ClassName", PLUGIN_CLASS)
+    graph.set("FileType", "NewFile")
+    graph.set("Source", source)
+    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 content_digest(zip_bytes: bytes) -> str:
+    """sha256 hex of the project.xml inside the package zip.
+
+    Digest the XML bytes, not the zip: ET.tostring is deterministic, zip
+    container bytes are not. This is the content-parity token (V4) — it
+    covers everything package_zip splices in, features included.
+    """
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+        return hashlib.sha256(zf.read("project.xml")).hexdigest()
+
+
+def package_description(zip_bytes: bytes) -> str:
+    """The import description: human text + the content digest.
+
+    The description is the one round-trip channel the CustomizationApi
+    offers (verified live vs 26.101.0225): the import's projectDescription
+    comes back only in the root description attribute of getProject's
+    re-serialized project.xml — getPublished rows hold names alone.
+    """
+    return f"{PACKAGE_DESCRIPTION} [sha256:{content_digest(zip_bytes)}]"
+
+
+def _published_description(client: AcumaticaClient) -> str | None:
+    """The description embedded in the tenant's published package, if any.
+
+    None when the project is gone (recreated tenant, B3) or its content
+    does not parse as a package — both mean "republish".
+    """
+    content = client.customization_project_content(PACKAGE_NAME)
+    if content is None:
+        return None
+    try:
+        with zipfile.ZipFile(io.BytesIO(content)) as zf:
+            root = ET.fromstring(zf.read("project.xml"))
+    except (zipfile.BadZipFile, KeyError, ET.ParseError):
+        return None
+    return root.get("description")
+
+
+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,
+    features: Sequence[str] | None = None,
+    timeout: float = 600.0,
+    poll: float = 5.0,
+) -> str:
+    """Publish the bootstrap package into the client's session tenant.
+
+    ``features`` (default: the built-in six) flows into the plugin's Enabled
+    set via package_zip. Idempotent on content, not existence (V4): the
+    import embeds the digest of the package we build now in the project
+    description, and the skip requires getPublished to list the package AND
+    the published description to carry that same digest. A recreated tenant
+    (stale publication row, content gone — B3) and a content change since
+    the last publish (B7 — e.g. an edited features.yaml) both fail the gate
+    and trigger reimport + republish. Otherwise 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.
+    """
+    zip_bytes = package_zip(features)
+    description = package_description(zip_bytes)
+    if PACKAGE_NAME in client.customization_published() and (
+        _published_description(client) == description
+    ):
+        return "already published"
+    client.customization_import(PACKAGE_NAME, zip_bytes, description=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 → acumatica_cli-0.4.0}/src/acumatica_cli/bootstrap_plugin.cs

@@ -11,6 +11,11 @@
 // 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).
+//
+// The Enabled set is NOT authored here (SPEC V2: feature flags are config
+// "what", never tool source - B6): package_zip() substitutes the
+// ACU_FEATURES sentinel below with the data repo's bootstrap/features.yaml
+// list (built-in six when the file is absent) at package-build time.
 using System.Collections.Generic;
 using System.Reflection;
 using PX.Data;
@@ -22,25 +27,32 @@ namespace AcuBootstrap
     {
         private static readonly HashSet<string> Enabled = new HashSet<string>
         {
-            "FinancialModule",
-            "FinancialStandard",
-            "DistributionModule",
-            "Inventory",
-            "Branch",
-            "MultiCompany",
+            /*ACU_FEATURES*/
         };
 
         public override void UpdateDatabase()
         {
             var flags = new List<PXDataFieldAssign>();
+            var known = new HashSet<string>();
             foreach (PropertyInfo prop in typeof(FeaturesSet).GetProperties())
             {
                 if (prop.PropertyType == typeof(bool?))
                 {
+                    known.Add(prop.Name);
                     flags.Add(new PXDataFieldAssign(
                         prop.Name, PXDbType.Bit, Enabled.Contains(prop.Name)));
                 }
             }
+            foreach (string name in Enabled)
+            {
+                if (!known.Contains(name))
+                {
+                    // silent-typo guard (T24): a misspelled features.yaml
+                    // entry enables nothing - say so in the publish log
+                    WriteLog("AcuBootstrap: unknown feature name '" + name
+                        + "' - no FeaturesSet property, nothing enabled");
+                }
+            }
             flags.Add(new PXDataFieldAssign("Status", PXDbType.Int, 0)); // Validated
 
             using (var tx = new PXTransactionScope())