acumatica-cli 0.10.3__tar.gz → 0.12.0__tar.gz

{acumatica_cli-0.10.3 → acumatica_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.10.3
+Version: 0.12.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -16,7 +16,7 @@ Project-URL: Homepage, https://lab5.ca
 Project-URL: Repository, https://github.com/kborovik/acumatica-cli
 Description-Content-Type: text/markdown
 
-# Acumatica GitOps (Config-as-Code)
+# Acumatica ERP - GitOps CLI
 
 **`acu`** configures Acumatica ERP from YAML files in a git repo (GitOps). 
 
@@ -43,10 +43,23 @@ cd my-erp                                # edit .env: set ACU_PASSWORD
 
 acu config check                         # read-only preflight (incl. target.yaml)
 acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
-acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
+acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/ (, master/)
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
 ```
 
+**Distribution demo seed** (inventory, warehouse, items, vendors/customers, lifecycle scenarios):
+
+```sh
+acu config init --flavor distribution --host erp.example.com my-dist
+cd my-dist                               # edit .env; start from an empty tenant
+acu config check && acu bootstrap \
+  && acu apply config/ && acu run scenario/ && acu diff config/
+# warm re-run: capital once-skips; Owner Capital stays 50000 (not 100000)
+acu run scenario/
+```
+
+See [docs/distribution.md](docs/distribution.md) for the entity map, once-guard, and apply-order notes.
+
 **Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
 
 ```sh
@@ -81,36 +94,42 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
-    ├── init [--host HOST] [DIR]      scaffold a data repo (.env, target.yaml, example YAML)
+    ├── init [--host HOST] [--flavor distribution] [DIR]
+    │                                 scaffold a data repo (.env, target.yaml, example YAML)
     ├── show                          print the resolved config as a complete .env
     └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
 
-`apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
-`run` called without FILES defaults to `scenario/`.
+`apply` and `diff` without FILES prefer `config/<name>/` when any seed child exists under `config/`; otherwise root `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
+A path like `config/` expands nested seed dirs in that fixed order.
+`run` without FILES defaults to `scenario/`.
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
 ## The data repo
 
-Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
+Your configuration lives in its own git repo.
+`acu config init` scaffolds finance-minimal seeds at the **root** (Bootstrap `project.xml` at `Bootstrap/1.0.0`, no `master/`, no scenario).
+`acu config init --flavor distribution` scaffolds the full demo under `config/` (same contract identity, expanded COA, masters) plus lifecycle `scenario/` and README.
 
-| 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            |
-| `scenario/`   | transaction scenarios for `acu run`: purchase, build, sell flows            |
-| `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where)         |
-| `.env`        | where to apply and who signs in, every key an `ACU_*` variable             |
+| Path | What it holds |
+| ---- | ------------- |
+| `bootstrap/` / `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
+| `baseline/` / `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs |
+| `setup/` / `config/setup/` | one-time actions: financial year, master calendar, open periods |
+| `config/master/` | distribution masters (prefs, warehouse, items, parties); flavor only |
+| `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build stub, sell |
+| `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
+| `.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.
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
-Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
+Seed YAML is state: `apply` upserts it, `diff` proves it.
 Scenario YAML is different — it describes transactions that flow forward.
-`acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so a scenario re-runs safely on a warm tenant.
+`acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
+`once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 
 ### Seed `endpoint:` symbols
 
@@ -121,7 +140,7 @@ Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:
 | omitted | `Default/<ACU_API_VERSION>` for Default-only entities |
 | `bootstrap` | active `Bootstrap/<ver>` from `bootstrap/project.xml` or the packaged contract |
 | `default` | `Default/<ACU_API_VERSION>` — tracks the operator API version |
-| `Bootstrap/1.9.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
+| `Bootstrap/1.0.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
 
 Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the configured API generation.
 
@@ -258,6 +277,16 @@ gmake check      # offline gate: ruff, basedpyright strict, pytest
 The default test suite is fully offline.
 REST is faked with `httpx.MockTransport`, SSH with a monkeypatched `subprocess.run` — no live instance is needed.
 `gmake check` must pass before every commit.
+GitHub Actions runs the same gate on every push and pull request to `main`.
+
+### Release
+
+```sh
+gmake release patch   # or minor | major
+```
+
+Local release runs `gmake check`, bumps the version, commits, tags `v<version>`, and pushes.
+GitHub Actions re-runs the check on the tag, then publishes the GitHub release and PyPI package only if that check passes.
 
 ### Live end-to-end tier
 

{acumatica_cli-0.10.3 → acumatica_cli-0.12.0}/README.md

@@ -1,4 +1,4 @@
-# Acumatica GitOps (Config-as-Code)
+# Acumatica ERP - GitOps CLI
 
 **`acu`** configures Acumatica ERP from YAML files in a git repo (GitOps). 
 
@@ -25,10 +25,23 @@ cd my-erp                                # edit .env: set ACU_PASSWORD
 
 acu config check                         # read-only preflight (incl. target.yaml)
 acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
-acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
+acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/ (, master/)
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
 ```
 
+**Distribution demo seed** (inventory, warehouse, items, vendors/customers, lifecycle scenarios):
+
+```sh
+acu config init --flavor distribution --host erp.example.com my-dist
+cd my-dist                               # edit .env; start from an empty tenant
+acu config check && acu bootstrap \
+  && acu apply config/ && acu run scenario/ && acu diff config/
+# warm re-run: capital once-skips; Owner Capital stays 50000 (not 100000)
+acu run scenario/
+```
+
+See [docs/distribution.md](docs/distribution.md) for the entity map, once-guard, and apply-order notes.
+
 **Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
 
 ```sh
@@ -63,36 +76,42 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
-    ├── init [--host HOST] [DIR]      scaffold a data repo (.env, target.yaml, example YAML)
+    ├── init [--host HOST] [--flavor distribution] [DIR]
+    │                                 scaffold a data repo (.env, target.yaml, example YAML)
     ├── show                          print the resolved config as a complete .env
     └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
 
-`apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
-`run` called without FILES defaults to `scenario/`.
+`apply` and `diff` without FILES prefer `config/<name>/` when any seed child exists under `config/`; otherwise root `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
+A path like `config/` expands nested seed dirs in that fixed order.
+`run` without FILES defaults to `scenario/`.
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
 ## The data repo
 
-Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
+Your configuration lives in its own git repo.
+`acu config init` scaffolds finance-minimal seeds at the **root** (Bootstrap `project.xml` at `Bootstrap/1.0.0`, no `master/`, no scenario).
+`acu config init --flavor distribution` scaffolds the full demo under `config/` (same contract identity, expanded COA, masters) plus lifecycle `scenario/` and README.
 
-| 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            |
-| `scenario/`   | transaction scenarios for `acu run`: purchase, build, sell flows            |
-| `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where)         |
-| `.env`        | where to apply and who signs in, every key an `ACU_*` variable             |
+| Path | What it holds |
+| ---- | ------------- |
+| `bootstrap/` / `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
+| `baseline/` / `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs |
+| `setup/` / `config/setup/` | one-time actions: financial year, master calendar, open periods |
+| `config/master/` | distribution masters (prefs, warehouse, items, parties); flavor only |
+| `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build stub, sell |
+| `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
+| `.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.
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
-Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
+Seed YAML is state: `apply` upserts it, `diff` proves it.
 Scenario YAML is different — it describes transactions that flow forward.
-`acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so a scenario re-runs safely on a warm tenant.
+`acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
+`once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 
 ### Seed `endpoint:` symbols
 
@@ -103,7 +122,7 @@ Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:
 | omitted | `Default/<ACU_API_VERSION>` for Default-only entities |
 | `bootstrap` | active `Bootstrap/<ver>` from `bootstrap/project.xml` or the packaged contract |
 | `default` | `Default/<ACU_API_VERSION>` — tracks the operator API version |
-| `Bootstrap/1.9.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
+| `Bootstrap/1.0.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
 
 Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the configured API generation.
 
@@ -240,6 +259,16 @@ gmake check      # offline gate: ruff, basedpyright strict, pytest
 The default test suite is fully offline.
 REST is faked with `httpx.MockTransport`, SSH with a monkeypatched `subprocess.run` — no live instance is needed.
 `gmake check` must pass before every commit.
+GitHub Actions runs the same gate on every push and pull request to `main`.
+
+### Release
+
+```sh
+gmake release patch   # or minor | major
+```
+
+Local release runs `gmake check`, bumps the version, commits, tags `v<version>`, and pushes.
+GitHub Actions re-runs the check on the tag, then publishes the GitHub release and PyPI package only if that check passes.
 
 ### Live end-to-end tier
 

{acumatica_cli-0.10.3 → acumatica_cli-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.10.3"
+version = "0.12.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 license = "PolyForm-Noncommercial-1.0.0"

{acumatica_cli-0.10.3 → acumatica_cli-0.12.0}/src/acumatica_cli/bootstrap.py

@@ -8,10 +8,11 @@ virgin tenant, so bootstrap = publish a package whose CustomizationPlugin
 cannot write CS100000 at all (T3 verdict) — and whose Bootstrap contract
 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.
+Contract ownership is hybrid (T69/V2/T81/T85): the data repo's
+``config/bootstrap/project.xml`` is preferred, then root
+``bootstrap/project.xml``; else the packaged full company
+``bootstrap_project.xml`` (``Bootstrap/1.0.0``) so PyPI-only and offline
+virgin paths still bootstrap the full surface.
 
 Customization publishes are tenant-scoped, so the package must be published
 per tenant; publish() is idempotent on content — the skip gate compares the
@@ -19,8 +20,9 @@ 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.
+reads config/bootstrap/features.yaml then root bootstrap/features.yaml
+(absent -> the built-in six) and package_zip() splices it into the plugin
+source at build time.
 """
 
 import hashlib
@@ -43,11 +45,10 @@ PACKAGE_NAME = "AcuBootstrap"
 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.
-# 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).
+# Code default when the data repo carries no 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",
@@ -59,8 +60,16 @@ DEFAULT_FEATURES = (
 FEATURES_SENTINEL = "/*ACU_FEATURES*/"
 
 
+def _bootstrap_file(root: Path, name: str) -> Path | None:
+    """Resolve a bootstrap package input: config/bootstrap then root (V30)."""
+    for path in (root / "config" / "bootstrap" / name, root / "bootstrap" / name):
+        if path.is_file():
+            return path
+    return None
+
+
 def packaged_contract_xml() -> bytes:
-    """The CLI-shipped minimal Bootstrap contract (config-init surface)."""
+    """The CLI-shipped full company Bootstrap contract (``Bootstrap/1.0.0``)."""
     return (resources.files("acumatica_cli") / "bootstrap_project.xml").read_bytes()
 
 
@@ -68,12 +77,13 @@ 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).
+    Prefer ``config/bootstrap/project.xml``, then root ``bootstrap/project.xml``
+    (V30 dual resolve). Absent root or file falls back to the packaged full
+    company contract (V2/T81, same absence pattern as features.yaml).
     """
     if root is not None:
-        path = root / "bootstrap" / "project.xml"
-        if path.is_file():
+        path = _bootstrap_file(root, "project.xml")
+        if path is not None:
             return path.read_bytes()
     return packaged_contract_xml()
 
@@ -97,15 +107,16 @@ 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.
+    """FeaturesSet property names from config/ then root bootstrap (V30).
 
+    Prefer ``config/bootstrap/features.yaml``, then ``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():
+    path = _bootstrap_file(root, "features.yaml")
+    if path is None:
         return list(DEFAULT_FEATURES)
     with open(path) as f:
         data = yaml.safe_load(f)
@@ -136,9 +147,9 @@ def package_zip(
     ``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.
+    Contract XML (V2/T69/T81/T85): ``contract`` when given; else
+    ``config/bootstrap/project.xml`` then ``bootstrap/project.xml`` under
+    ``root`` when present; else the packaged full company template.
     """
     pkg = resources.files("acumatica_cli")
     if contract is None: