acumatica-cli 0.8.3__tar.gz → 0.9.1__tar.gz

{acumatica_cli-0.8.3 → acumatica_cli-0.9.1}/PKG-INFO

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

{acumatica_cli-0.8.3 → acumatica_cli-0.9.1}/pyproject.toml

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

{acumatica_cli-0.8.3 → acumatica_cli-0.9.1}/src/acumatica_cli/bootstrap.py

@@ -6,10 +6,12 @@ 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).
+endpoint exposes the seeding surface (serialization verified T12).
+
+Contract ownership is hybrid (T69/V2): the data repo's
+``bootstrap/project.xml`` is preferred when present (full company surface);
+else the packaged minimal ``bootstrap_project.xml`` covers config-init +
+the GL chain so PyPI-only and offline virgin paths still bootstrap.
 
 Customization publishes are tenant-scoped, so the package must be published
 per tenant; publish() is idempotent on content — the skip gate compares the
@@ -38,13 +40,8 @@ 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"
+_ENDPOINT_NS = "{http://www.acumatica.com/entity/maintenance/5.31}"
 
 # Code default when the data repo carries no bootstrap/features.yaml
 # (SPEC I.data) — the minimum for company/branch + baseline seeding.
@@ -62,6 +59,43 @@ DEFAULT_FEATURES = (
 FEATURES_SENTINEL = "/*ACU_FEATURES*/"
 
 
+def packaged_contract_xml() -> bytes:
+    """The CLI-shipped minimal Bootstrap contract (config-init surface)."""
+    return (resources.files("acumatica_cli") / "bootstrap_project.xml").read_bytes()
+
+
+def load_contract_xml(root: Path | None = None) -> bytes:
+    """Active contract bytes: data-repo override when present, else packaged.
+
+    ``root`` is the data-repo discovery root (the dir holding ``.env``).
+    Absent root or absent ``bootstrap/project.xml`` falls back to the
+    packaged minimal contract (V2, same absence pattern as features.yaml).
+    """
+    if root is not None:
+        path = root / "bootstrap" / "project.xml"
+        if path.is_file():
+            return path.read_bytes()
+    return packaged_contract_xml()
+
+
+def parse_endpoint(xml: bytes) -> tuple[str, frozenset[str]]:
+    """Endpoint ``Name/version`` + entity names from a contract project.xml."""
+    root = ET.fromstring(xml)
+    endpoint = root.find(f"EntityEndpoint/{_ENDPOINT_NS}Endpoint")
+    if endpoint is None:
+        raise RuntimeError("bootstrap contract: no EntityEndpoint/Endpoint item")
+    name = f"{endpoint.get('name')}/{endpoint.get('version')}"
+    entities = frozenset(
+        e.get("name", "") for e in endpoint.findall(f"{_ENDPOINT_NS}TopLevelEntity")
+    )
+    return name, entities
+
+
+# Authored once on the packaged template's root description — kept for
+# tests that pin a pre-digest stale description (V4 republish path).
+PACKAGE_DESCRIPTION = ET.fromstring(packaged_contract_xml()).get("description", "")
+
+
 def load_features(root: Path) -> list[str]:
     """The FeaturesSet property names from <root>/bootstrap/features.yaml.
 
@@ -85,7 +119,12 @@ def load_features(root: Path) -> list[str]:
     return list(data)
 
 
-def package_zip(features: Sequence[str] | None = None) -> bytes:
+def package_zip(
+    features: Sequence[str] | None = None,
+    *,
+    root: Path | None = None,
+    contract: bytes | 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
@@ -96,9 +135,21 @@ def package_zip(features: Sequence[str] | None = None) -> bytes:
     ``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).
+
+    Contract XML (V2/T69): ``contract`` when given; else
+    ``bootstrap/project.xml`` under ``root`` when present; else the
+    packaged minimal template.
     """
     pkg = resources.files("acumatica_cli")
-    root = ET.fromstring((pkg / "bootstrap_project.xml").read_bytes())
+    if contract is None:
+        if root is None:
+            from .config import find_data_root
+
+            root = find_data_root()
+        xml = load_contract_xml(root)
+    else:
+        xml = contract
+    root_el = ET.fromstring(xml)
     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")
@@ -106,13 +157,13 @@ def package_zip(features: Sequence[str] | None = None) -> bytes:
     source = source.replace(
         FEATURES_SENTINEL, ", ".join(f'"{name}"' for name in enabled)
     )
-    graph = ET.SubElement(root, "Graph")
+    graph = ET.SubElement(root_el, "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"))
+        zf.writestr("project.xml", ET.tostring(root_el, encoding="utf-8"))
     return buf.getvalue()
 
 
@@ -134,8 +185,12 @@ def package_description(zip_bytes: bytes) -> str:
     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.
+    Root description is read from the package's own project.xml so a
+    data-repo contract carries its own prose (V2).
     """
-    return f"{PACKAGE_DESCRIPTION} [sha256:{content_digest(zip_bytes)}]"
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+        desc = ET.fromstring(zf.read("project.xml")).get("description", "")
+    return f"{desc} [sha256:{content_digest(zip_bytes)}]"
 
 
 def _published_description(client: AcumaticaClient) -> str | None:
@@ -169,6 +224,8 @@ def _log_tail(status: dict[str, object], limit: int = 5) -> str:
 def publish(
     client: AcumaticaClient,
     features: Sequence[str] | None = None,
+    *,
+    root: Path | None = None,
     timeout: float = 600.0,
     poll: float = 5.0,
 ) -> str:
@@ -187,7 +244,7 @@ def publish(
     site may briefly drop connections mid-publish. Raises RuntimeError on a
     failed publish or on timeout.
     """
-    zip_bytes = package_zip(features)
+    zip_bytes = package_zip(features, root=root)
     description = package_description(zip_bytes)
     if PACKAGE_NAME in client.customization_published() and (
         _published_description(client) == description

acumatica_cli-0.9.1/src/acumatica_cli/bootstrap_project.xml

@@ -0,0 +1,238 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  acu bootstrap customization package template - minimal config-init surface
+  (SPEC T69 hybrid A).
+
+  package_zip() (bootstrap.py) prefers data-repo bootstrap/project.xml when
+  present; otherwise this packaged template is the fallback so config init,
+  offline tests, and PyPI-only installs still bootstrap.
+
+  package_zip() injects a
+  <Graph ClassName="AcuBootstrapPlugin" FileType="NewFile" Source="..."/>
+  item carrying bootstrap_plugin.cs - the CustomizationPlugin that enables
+  features on publish (CS100000 is un-writable through the contract API;
+  T3 verdict). Item shape verified vs 26.101.0225: Customization.CstCodeFile
+  Tag=Graph, source rides in the Source ATTRIBUTE (XML-escaped), not CDATA.
+
+  Root element shape verified vs the training packages shipped on the live
+  box (HelpAndTraining/T*/PhoneRepairShop.zip, same 26.101.0225 build):
+  project.xml's root is <Customization level description product-version>;
+  the project NAME comes from the import call, not the XML.
+
+  The <EntityEndpoint> item (T12, verified vs 26.101.0225 by import
+  round-trip 2026-07-08): the <Endpoint> child is the XmlSerializer form of
+  PX.Api.ContractBased.Common.Model.Endpoint - namespace
+  http://www.acumatica.com/entity/maintenance/5.31, systemContractVersion 4.
+
+  Minimal entity payload (config-init + GL chain only; full company surface
+  lives in the data repo's bootstrap/project.xml per T69):
+  - Company    CS101500 -> OrganizationMaint, PrimaryView BAccount
+  - CreditTerms CS206500 -> TermsMaint, PrimaryView TermsDef
+  - LedgerCompany GL201500 -> GeneralLedgerMaint (org-ledger link, B12)
+  - FinancialYearSettings GL101000 + GeneratePeriods (AutoFill)
+  - MasterCalendar GL201000 + GenerateCalendar (GenerateYears)
+  - CompanyCalendar / CompanyPeriod GL201100 (done_when probes)
+  - ManagePeriods GL503000 + ProcessAll (period activation, B13)
+  - GLPreferences GL102000 (YtdNetIncAccountID + RetEarnAccountID)
+
+  Contract field names = DAC property names verbatim (no rename layer).
+  Features (CS100000) stays OUT of the endpoint - the plugin owns features.
+-->
+<Customization level="" description="acu bootstrap: CustomizationPlugin enables features on publish; Bootstrap endpoint exposes company + credit terms + GL preferences + ledger-company link + financial year + calendars + period activation (config-init surface; full company contract lives in data-repo bootstrap/project.xml)" product-version="26.101">
+  <EntityEndpoint>
+    <Endpoint xmlns="http://www.acumatica.com/entity/maintenance/5.31" name="Bootstrap" version="1.9.0" systemContractVersion="4">
+      <TopLevelEntity name="Company" screen="CS101500">
+        <Fields>
+          <Field name="AcctCD" type="StringValue" />
+          <Field name="AcctName" type="StringValue" />
+          <Field name="OrganizationType" type="StringValue" />
+          <Field name="BaseCuryID" type="StringValue" />
+          <Field name="CountryID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="AcctCD">
+            <To object="BAccount" field="AcctCD" />
+          </Mapping>
+          <Mapping field="AcctName">
+            <To object="BAccount" field="AcctName" />
+          </Mapping>
+          <Mapping field="OrganizationType">
+            <To object="OrganizationView" field="OrganizationType" />
+          </Mapping>
+          <Mapping field="BaseCuryID">
+            <To object="OrganizationView" field="BaseCuryID" />
+          </Mapping>
+          <Mapping field="CountryID">
+            <To object="AddressDummy" field="CountryID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="CreditTerms" screen="CS206500">
+        <Fields>
+          <Field name="TermsID" type="StringValue" />
+          <Field name="Descr" type="StringValue" />
+          <Field name="VisibleTo" type="StringValue" />
+          <Field name="DueType" type="StringValue" />
+          <Field name="DayDue00" type="ShortValue" />
+          <Field name="DiscType" type="StringValue" />
+          <Field name="DiscPercent" type="DecimalValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="TermsID">
+            <To object="TermsDef" field="TermsID" />
+          </Mapping>
+          <Mapping field="Descr">
+            <To object="TermsDef" field="Descr" />
+          </Mapping>
+          <Mapping field="VisibleTo">
+            <To object="TermsDef" field="VisibleTo" />
+          </Mapping>
+          <Mapping field="DueType">
+            <To object="TermsDef" field="DueType" />
+          </Mapping>
+          <Mapping field="DayDue00">
+            <To object="TermsDef" field="DayDue00" />
+          </Mapping>
+          <Mapping field="DiscType">
+            <To object="TermsDef" field="DiscType" />
+          </Mapping>
+          <Mapping field="DiscPercent">
+            <To object="TermsDef" field="DiscPercent" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="LedgerCompany" screen="GL201500">
+        <Fields>
+          <Field name="LedgerCD" type="StringValue" />
+          <Field name="OrganizationID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="LedgerCD">
+            <To object="LedgerRecords" field="LedgerCD" />
+          </Mapping>
+          <Mapping field="OrganizationID">
+            <To object="OrganizationLedgerLinkWithOrganizationSelect" field="OrganizationID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="FinancialYearSettings" screen="GL101000">
+        <Fields>
+          <Field name="BegFinYear" type="DateTimeValue" />
+          <Field name="FinPeriods" type="ShortValue" />
+          <Field name="PeriodType" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="BegFinYear">
+            <To object="FiscalYearSetup" field="BegFinYear" />
+          </Mapping>
+          <Mapping field="FinPeriods">
+            <To object="FiscalYearSetup" field="FinPeriods" />
+          </Mapping>
+          <Mapping field="PeriodType">
+            <To object="FiscalYearSetup" field="PeriodType" />
+          </Mapping>
+        </Mappings>
+        <Actions>
+          <Action name="GeneratePeriods" mappedTo="AutoFill" isDefault="false" />
+        </Actions>
+      </TopLevelEntity>
+      <TopLevelEntity name="MasterCalendar" screen="GL201000">
+        <Fields>
+          <Field name="FinancialYear" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="FinancialYear">
+            <To object="FiscalYear" field="Year" />
+          </Mapping>
+        </Mappings>
+        <Actions>
+          <Action name="GenerateCalendar" mappedTo="GenerateYears" isDefault="false">
+            <Fields>
+              <Field name="FromYear" type="StringValue" />
+              <Field name="ToYear" type="StringValue" />
+            </Fields>
+            <Mappings>
+              <Mapping field="FromYear">
+                <To object="GenerateParams" field="FromYear" />
+              </Mapping>
+              <Mapping field="ToYear">
+                <To object="GenerateParams" field="ToYear" />
+              </Mapping>
+            </Mappings>
+          </Action>
+        </Actions>
+      </TopLevelEntity>
+      <TopLevelEntity name="CompanyCalendar" screen="GL201100">
+        <Fields>
+          <Field name="FinancialYear" type="StringValue" />
+          <Field name="OrganizationID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="FinancialYear">
+            <To object="OrgFinYear" field="Year" />
+          </Mapping>
+          <Mapping field="OrganizationID">
+            <To object="OrgFinYear" field="OrganizationID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="CompanyPeriod" screen="GL201100">
+        <Fields>
+          <Field name="FinancialYear" type="StringValue" />
+          <Field name="FinPeriodID" type="StringValue" />
+          <Field name="Status" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="FinancialYear">
+            <To object="OrgFinPeriods" field="FinYear" />
+          </Mapping>
+          <Mapping field="FinPeriodID">
+            <To object="OrgFinPeriods" field="FinPeriodID" />
+          </Mapping>
+          <Mapping field="Status">
+            <To object="OrgFinPeriods" field="Status" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="ManagePeriods" screen="GL503000">
+        <Fields>
+          <Field name="Action" type="StringValue" />
+          <Field name="FromYear" type="StringValue" />
+          <Field name="ToYear" type="StringValue" />
+          <Field name="OrganizationID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="Action">
+            <To object="Filter" field="Action" />
+          </Mapping>
+          <Mapping field="FromYear">
+            <To object="Filter" field="FromYear" />
+          </Mapping>
+          <Mapping field="ToYear">
+            <To object="Filter" field="ToYear" />
+          </Mapping>
+          <Mapping field="OrganizationID">
+            <To object="Filter" field="OrganizationID" />
+          </Mapping>
+        </Mappings>
+        <Actions>
+          <Action name="ProcessAll" mappedTo="ProcessAll" isDefault="false" />
+        </Actions>
+      </TopLevelEntity>
+      <TopLevelEntity name="GLPreferences" screen="GL102000">
+        <Fields>
+          <Field name="YtdNetIncAccountID" type="StringValue" />
+          <Field name="RetEarnAccountID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="YtdNetIncAccountID">
+            <To object="GLSetupRecord" field="YtdNetIncAccountID" />
+          </Mapping>
+          <Mapping field="RetEarnAccountID">
+            <To object="GLSetupRecord" field="RetEarnAccountID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+    </Endpoint>
+  </EntityEndpoint>
+</Customization>

{acumatica_cli-0.8.3 → acumatica_cli-0.9.1}/src/acumatica_cli/client.py

@@ -93,6 +93,9 @@ class AcumaticaClient:
         self._http = httpx.Client(
             base_url=instance.base_url, timeout=timeout, transport=transport
         )
+        # V5/B24: first successful Company PUT this session → one re-login
+        # so later branch selectors resolve; warm re-PUT is re-login-safe
+        self._refreshed_after_company = False
 
     def __enter__(self) -> AcumaticaClient:
         # tenant guard (V5, docs/rest-api.md): an omitted or empty tenant is
@@ -105,27 +108,10 @@ class AcumaticaClient:
                 "an explicit tenant silently lands on the default tenant; "
                 "set ACU_TENANT in .env or pass --tenant"
             )
-        creds: dict[str, str] = {
-            "name": self.instance.user,
-            "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).
+        # logout first on failure: __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"
-                )
+            self._login()
         except BaseException:
             self.__exit__()
             raise
@@ -138,6 +124,50 @@ class AcumaticaClient:
         finally:
             self._http.close()
 
+    def _login(self) -> None:
+        """POST login + refuse on landed-tenant mismatch (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).
+        """
+        creds: dict[str, str] = {
+            "name": self.instance.user,
+            "password": self.instance.password,
+            "tenant": self.instance.tenant,
+        }
+        self._checked(self._http.post("/entity/auth/login", json=creds))
+        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"
+            )
+
+    def relogin(self) -> None:
+        """Drop the cookie session and open a new one without closing transport.
+
+        Mid-session Company create leaves branch selectors empty until a
+        fresh login (V5, B24). Unlike ``__exit__``, the httpx client stays
+        open so the outer context manager still owns the session lifecycle.
+        """
+        # empty body → Content-Length: 0 (V6 / IIS 411)
+        self._http.post("/entity/auth/logout", content=b"")
+        self._login()
+
+    def refresh_after_company(self) -> None:
+        """Re-login once after the first successful Company PUT this session.
+
+        Warm-tenant Company re-PUT is re-login-safe (V5); further Company
+        records in the same run skip the second bounce.
+        """
+        if self._refreshed_after_company:
+            return
+        self.relogin()
+        self._refreshed_after_company = True
+
     def _landed_tenant(self) -> str:
         """The tenant this session actually landed on (login name).