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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.11.0
+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>
@@ -47,15 +47,18 @@ acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/ (,
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
 ```
 
-**Distribution demo seed** (inventory, warehouse, items, vendors/customers, golden scenario):
+**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 && acu run scenario/ && acu diff
+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 and apply-order notes.
+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.
 
@@ -97,34 +100,36 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
     └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
 
-`apply` and `diff` called without FILES default to existing scaffolded directories, in order: `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
-`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 finance-minimal seeds (Bootstrap `project.xml` at `Bootstrap/1.0.0`, no `master/`).
-`acu config init --flavor distribution` adds the full demo set (same contract identity, expanded COA, `master/`, golden `scenario/`, 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            |
-| `master/`     | distribution masters (prefs, warehouse, items, vendors, customers); flavor only |
-| `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             |
+`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/` / `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
 

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

@@ -29,15 +29,18 @@ acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/ (,
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
 ```
 
-**Distribution demo seed** (inventory, warehouse, items, vendors/customers, golden scenario):
+**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 && acu run scenario/ && acu diff
+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 and apply-order notes.
+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.
 
@@ -79,34 +82,36 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
     └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
 
-`apply` and `diff` called without FILES default to existing scaffolded directories, in order: `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
-`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 finance-minimal seeds (Bootstrap `project.xml` at `Bootstrap/1.0.0`, no `master/`).
-`acu config init --flavor distribution` adds the full demo set (same contract identity, expanded COA, `master/`, golden `scenario/`, 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            |
-| `master/`     | distribution masters (prefs, warehouse, items, vendors, customers); flavor only |
-| `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             |
+`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/` / `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
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.11.0"
+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.11.0 → 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/T81): the data repo's
-``bootstrap/project.xml`` is preferred when present; else the packaged
-full company ``bootstrap_project.xml`` (``Bootstrap/1.0.0``) so PyPI-only
-and offline virgin paths still bootstrap the full surface.
+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,6 +60,14 @@ 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 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 full company contract (V2/T81, 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/T81): ``contract`` when given; else
-    ``bootstrap/project.xml`` under ``root`` when present; else the
-    packaged full company 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:

{acumatica_cli-0.11.0 → acumatica_cli-0.12.0}/src/acumatica_cli/cli.py

@@ -428,26 +428,27 @@ def config_init(host: str | None, flavor: str | None, directory: Path | None) ->
     Templates ship with the package; every value is a placeholder or a
     verified minimal example - no secrets. Both flavors scaffold the full
     company ``bootstrap/project.xml`` (Bootstrap/1.0.0). ``--flavor
-    distribution`` adds expanded COA, master/, scenario/, and README (V28).
-    Existing files are never overwritten (reported as skipped). DIRECTORY
-    defaults to the current directory and is created if absent. No git
-    init, no gpg.
+    distribution`` scaffolds under ``config/`` + lifecycle ``scenario/``
+    + README (V28/T87). Existing files are never overwritten (reported as
+    skipped). DIRECTORY defaults to the current directory and is created
+    if absent. No git init, no gpg.
     """
     target = directory or Path.cwd()
     for action, path in scaffold(target, host=host, flavor=flavor):
         suffix = " (exists)" if action == "skip" else ""
         output.data(f"{action} {path}{suffix}")
-    # next-step cmds (issue #18): operator rebuild order after scaffold
+    # next-step cmds (issue #18/#19): operator rebuild order after scaffold
     output.data("")
     output.data("next:")
     output.data("  1. edit .env (set ACU_PASSWORD, ACU_TENANT; keep ACU_API_VERSION)")
     output.data("  2. acu config check")
     output.data("  3. acu bootstrap          # or: acu tenant create ... (SSH)")
-    output.data("  4. acu apply")
     if flavor == "distribution":
+        output.data("  4. acu apply config/")
         output.data("  5. acu run scenario/")
-        output.data("  6. acu diff")
+        output.data("  6. acu diff config/")
     else:
+        output.data("  4. acu apply")
         output.data("  5. acu diff")
 
 
@@ -627,37 +628,60 @@ def _probe_endpoints(client: AcumaticaClient, inst: Instance) -> bool:
 SEED_DIRS = ("bootstrap", "baseline", "setup", "master")
 
 
+def _seed_child_dirs(parent: Path) -> list[Path]:
+    """SEED_DIRS children of ``parent`` that exist, fixed order (V22/V30)."""
+    return [parent / name for name in SEED_DIRS if (parent / name).is_dir()]
+
+
 def default_seed_dirs() -> tuple[Path, ...]:
-    """The init-scaffolded seed dirs that exist at the data-repo root.
-
-    apply and diff default to these when called with no FILES, in fixed
-    order (bootstrap, baseline, setup, master); only dirs that exist are
-    included (finance-minimal has no master/; distribution does). The data
-    repo is the .env dir (V3 walk-up). None existing is an error - an empty
-    default would make a bare run a silent no-op. Paths come back relative
-    to cwd (the root is always cwd or an ancestor), so a bare run prints
-    exactly what naming the dirs would.
+    """Default apply/diff dirs: prefer ``config/`` SEED_DIRS, else root (V30).
+
+    When the data-repo ``config/`` has any SEED_DIRS child, only those
+    ``config/<name>/`` paths are returned (dual layout never merges with
+    root). Else root ``bootstrap/``…``master/`` for present names
+    (finance-minimal). The data repo is the .env dir (V3 walk-up). None
+    existing is an error - an empty default would make a bare run a silent
+    no-op. Paths come back relative to cwd so a bare run prints exactly
+    what naming the dirs would.
     """
     root = data_root()
-    dirs = tuple(
-        Path(os.path.relpath(d)) for name in SEED_DIRS if (d := root / name).is_dir()
-    )
+    config = root / "config"
+    if config.is_dir() and _seed_child_dirs(config):
+        parents = _seed_child_dirs(config)
+    else:
+        parents = _seed_child_dirs(root)
+    dirs = tuple(Path(os.path.relpath(d)) for d in parents)
     if not dirs:
         expected = ", ".join(f"{name}/" for name in SEED_DIRS)
-        raise SystemExit(f"{root}: none of the seed directories exist ({expected})")
+        raise SystemExit(
+            f"{root}: none of the seed directories exist (config/<name>/ or {expected})"
+        )
     return dirs
 
 
+def _leaf_yaml(directory: Path) -> list[Path]:
+    """Sorted ``*.yaml`` in a leaf seed dir; skip ``features.yaml`` (I.data)."""
+    return sorted(p for p in directory.glob("*.yaml") if p.name != "features.yaml")
+
+
 def expand_files(files: tuple[Path, ...]) -> list[Path]:
-    """Expand directory arguments into their *.yaml files, sorted.
+    """Expand directory arguments into seed ``*.yaml`` files (V22/V30).
 
-    features.yaml is skipped: it configures the bootstrap package build
-    (a feature-name list, SPEC I.data), not an entity/records seed file.
+    A dir with any SEED_DIRS child (umbrella e.g. ``config/``) expands those
+    nested subdirs in fixed SEED_DIRS order, then leaf ``*.yaml`` per subdir.
+    A leaf dir expands its own ``*.yaml`` only. ``features.yaml`` is skipped:
+    it configures the bootstrap package build, not an entity/records seed.
     """
     paths: list[Path] = []
     for path in files:
         if path.is_dir():
-            found = sorted(p for p in path.glob("*.yaml") if p.name != "features.yaml")
+            children = _seed_child_dirs(path)
+            if children:
+                found: list[Path] = []
+                for child in children:
+                    found += _leaf_yaml(child)
+            else:
+                found = _leaf_yaml(path)
             if not found:
                 raise SystemExit(f"{path}: no seed *.yaml files in directory")
             paths += found
@@ -675,9 +699,10 @@ def expand_files(files: tuple[Path, ...]) -> list[Path]:
 def apply_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
     """Seed baseline YAML into the tenant (idempotent PUT upserts).
 
-    FILES are baseline YAML files or directories containing them. Omitted,
-    they default to the data repo's existing init-scaffolded directories in
-    fixed order: bootstrap/, baseline/, setup/, master/ (when present).
+    FILES are baseline YAML files or directories containing them. A dir with
+    SEED_DIRS children (e.g. config/) expands nested trees in fixed order.
+    Omitted, defaults prefer config/<name>/ when present, else root SEED_DIRS
+    (V30).
     """
     assert_target_compatible(inst)
     with AcumaticaClient(inst) as client:
@@ -729,9 +754,10 @@ def schema_cmd(inst: Instance, out_dir: Path | None) -> None:
 def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
     """Compare baseline YAML against the live tenant; exit 2 on drift.
 
-    FILES are baseline YAML files or directories containing them. Omitted,
-    they default to the data repo's existing init-scaffolded directories in
-    fixed order: bootstrap/, baseline/, setup/, master/ (when present).
+    FILES are baseline YAML files or directories containing them. A dir with
+    SEED_DIRS children (e.g. config/) expands nested trees in fixed order.
+    Omitted, defaults prefer config/<name>/ when present, else root SEED_DIRS
+    (V30).
     """
     assert_target_compatible(inst)
     paths = expand_files(files or default_seed_dirs())