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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.8.1
+Version: 0.8.3
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -40,11 +40,24 @@ 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 create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
 acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
 ```
 
+**Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
+
+```sh
+acu config init --host customer.acumatica.com my-erp
+cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; ACU_SSH=
+acu config check                         # REST preflight; ssh probe is skipped
+acu --tenant DEV bootstrap               # publish AcuBootstrap via REST only
+acu --tenant DEV apply
+acu --tenant DEV diff
+# offline UI fallback when REST publish is blocked:
+acu bootstrap --export AcuBootstrap.zip  # import + publish on SM204505
+```
+
 ## CLI map
 
 ```text
@@ -53,10 +66,11 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 │
 ├── 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
+│   ├── create --id N --login NAME    create + bootstrap; re-run to republish (SSH)
 │   │          [--type SalesDemo|T100|U100] [--parent N] [--hidden] [--no-init]
 │   └── delete --id N [--yes]         delete the tenant and its data, recycle app pool
 │
+├── bootstrap [--export PATH]         publish AcuBootstrap (REST); --export = offline zip
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
@@ -116,16 +130,20 @@ Everything lives in one `.env` file: *where* to apply and *who* signs in. Three
 ```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_SSH=Administrator@acu-dev1.vm.internal             # optional: control-plane user@host (tenant CRUD)
 ACU_USER=admin                                         # optional, defaults to admin
-ACU_PASSWORD=...                                       # required
+ACU_PASSWORD=...                                       # required for live commands
 ```
 
 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`.
+- 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.
+- `ACU_SSH` is optional.
+- Leave it blank on hosted instances; only `acu tenant` needs it.
+- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the 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:
 
@@ -139,9 +157,11 @@ acu apply --dry-run    # show what would be written, write nothing
 `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`, `run`, `extract`, 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).
+- **Data plane (REST):** `acu bootstrap`, `apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API and CustomizationApi — see [`docs/rest-api.md`](docs/rest-api.md).
 
-If you never touch `acu tenant`, you never need SSH — every other command is pure REST.
+If you never touch `acu tenant`, you never need SSH.
+On a hosted instance, publish AcuBootstrap with `acu bootstrap`, then seed with `apply`.
+`acu bootstrap --export PATH` writes the package zip for manual import on the Customization Projects screen (SM204505) when you cannot call the API.
 
 ## SSH setup (control plane)
 
@@ -188,29 +208,33 @@ ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersi
 
 ## Development
 
+Requires **GNU Make at least 3.82** — the Makefile uses `.ONESHELL`.
+On macOS use Homebrew's `gmake` (`brew install make`); `/usr/bin/make` is 3.81 and fails the guard.
+Elsewhere plain `make` is fine when it is GNU Make.
+
 ```sh
 git clone https://github.com/kborovik/acumatica-cli.git
 cd acumatica-cli
-make install    # editable install as a global uv tool
-make check      # offline gate: ruff, basedpyright strict, pytest
+gmake install    # editable install as a global uv tool
+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.
-`make check` must pass before every commit.
+`gmake check` must pass before every commit.
 
 ### Live end-to-end tier
 
-`make e2e` runs the opt-in live tier against a real Acumatica instance (pytest marker `e2e`, deselected by the default suite).
+`gmake e2e` runs the opt-in live tier against a real Acumatica instance (pytest marker `e2e`, deselected by the default suite).
 
 Configuration is one file: a decrypted `.env` at the repo root names the instance — `ACU_BASE_URL`, `ACU_SSH`, `ACU_TENANT`, `ACU_PASSWORD`.
-`make e2e` refuses to start without it.
+`gmake e2e` refuses to start without it.
 
 The tier is self-contained.
 Each run scaffolds a synthetic single-org company from the packaged `acu config init` templates into a temporary directory, copies the real `.env` into it, and runs the installed `acu` binary from there — no data repo, no pre-existing fixtures on the instance.
 Scratch tenants (`E2E`, `E2EA`, `E2EB`) are created on the way in and always deleted on the way out, so nothing persists.
 
 ```sh
-make e2e                                # whole tier, about 20 minutes
-make e2e FILE=test_provision_lifecycle  # one file, by stem or path
+gmake e2e                                # whole tier, about 20 minutes
+gmake e2e FILE=test_provision_lifecycle  # one file, by stem or path
 ```

{acumatica_cli-0.8.1 → acumatica_cli-0.8.3}/README.md

@@ -23,11 +23,24 @@ 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 create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
 acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
 ```
 
+**Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
+
+```sh
+acu config init --host customer.acumatica.com my-erp
+cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; ACU_SSH=
+acu config check                         # REST preflight; ssh probe is skipped
+acu --tenant DEV bootstrap               # publish AcuBootstrap via REST only
+acu --tenant DEV apply
+acu --tenant DEV diff
+# offline UI fallback when REST publish is blocked:
+acu bootstrap --export AcuBootstrap.zip  # import + publish on SM204505
+```
+
 ## CLI map
 
 ```text
@@ -36,10 +49,11 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 │
 ├── 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
+│   ├── create --id N --login NAME    create + bootstrap; re-run to republish (SSH)
 │   │          [--type SalesDemo|T100|U100] [--parent N] [--hidden] [--no-init]
 │   └── delete --id N [--yes]         delete the tenant and its data, recycle app pool
 │
+├── bootstrap [--export PATH]         publish AcuBootstrap (REST); --export = offline zip
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
@@ -99,16 +113,20 @@ Everything lives in one `.env` file: *where* to apply and *who* signs in. Three
 ```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_SSH=Administrator@acu-dev1.vm.internal             # optional: control-plane user@host (tenant CRUD)
 ACU_USER=admin                                         # optional, defaults to admin
-ACU_PASSWORD=...                                       # required
+ACU_PASSWORD=...                                       # required for live commands
 ```
 
 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`.
+- 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.
+- `ACU_SSH` is optional.
+- Leave it blank on hosted instances; only `acu tenant` needs it.
+- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the 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:
 
@@ -122,9 +140,11 @@ acu apply --dry-run    # show what would be written, write nothing
 `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`, `run`, `extract`, 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).
+- **Data plane (REST):** `acu bootstrap`, `apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API and CustomizationApi — see [`docs/rest-api.md`](docs/rest-api.md).
 
-If you never touch `acu tenant`, you never need SSH — every other command is pure REST.
+If you never touch `acu tenant`, you never need SSH.
+On a hosted instance, publish AcuBootstrap with `acu bootstrap`, then seed with `apply`.
+`acu bootstrap --export PATH` writes the package zip for manual import on the Customization Projects screen (SM204505) when you cannot call the API.
 
 ## SSH setup (control plane)
 
@@ -171,29 +191,33 @@ ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersi
 
 ## Development
 
+Requires **GNU Make at least 3.82** — the Makefile uses `.ONESHELL`.
+On macOS use Homebrew's `gmake` (`brew install make`); `/usr/bin/make` is 3.81 and fails the guard.
+Elsewhere plain `make` is fine when it is GNU Make.
+
 ```sh
 git clone https://github.com/kborovik/acumatica-cli.git
 cd acumatica-cli
-make install    # editable install as a global uv tool
-make check      # offline gate: ruff, basedpyright strict, pytest
+gmake install    # editable install as a global uv tool
+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.
-`make check` must pass before every commit.
+`gmake check` must pass before every commit.
 
 ### Live end-to-end tier
 
-`make e2e` runs the opt-in live tier against a real Acumatica instance (pytest marker `e2e`, deselected by the default suite).
+`gmake e2e` runs the opt-in live tier against a real Acumatica instance (pytest marker `e2e`, deselected by the default suite).
 
 Configuration is one file: a decrypted `.env` at the repo root names the instance — `ACU_BASE_URL`, `ACU_SSH`, `ACU_TENANT`, `ACU_PASSWORD`.
-`make e2e` refuses to start without it.
+`gmake e2e` refuses to start without it.
 
 The tier is self-contained.
 Each run scaffolds a synthetic single-org company from the packaged `acu config init` templates into a temporary directory, copies the real `.env` into it, and runs the installed `acu` binary from there — no data repo, no pre-existing fixtures on the instance.
 Scratch tenants (`E2E`, `E2EA`, `E2EB`) are created on the way in and always deleted on the way out, so nothing persists.
 
 ```sh
-make e2e                                # whole tier, about 20 minutes
-make e2e FILE=test_provision_lifecycle  # one file, by stem or path
+gmake e2e                                # whole tier, about 20 minutes
+gmake e2e FILE=test_provision_lifecycle  # one file, by stem or path
 ```

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

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.8.1"
+version = "0.8.3"
 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.1 → acumatica_cli-0.8.3}/src/acumatica_cli/cli.py

@@ -282,32 +282,102 @@ def _init_tenant(inst: Instance, mgr: TenantManager, login_name: str) -> None:
     output.success(f"admin {result}; tenant {login_name} is ready")
 
 
-def _bootstrap_tenant(inst: Instance, mgr: TenantManager, login_name: str) -> None:
-    """Publish the bootstrap package into the fresh tenant (data plane).
+def _bootstrap_features() -> list[str] | None:
+    """Feature list from the data repo, or None → package-built-in six.
 
-    Idempotent on content, not existence (V4): publish() skips only when the
-    published package carries the digest of the package built now. The
-    session targets the new tenant explicitly (V5), never a config default.
-    The feature set is data (V2): bootstrap/features.yaml in the data repo,
-    no data repo or no file -> the built-in six.
+    features.yaml is package-build config (V2), not a seed file: both the
+    live publish path and --export read it the same way.
     """
-    inst = inst.model_copy(update={"tenant": login_name})
     root = find_data_root()
-    features = bootstrap.load_features(root) if root is not None else None
+    return bootstrap.load_features(root) if root is not None else None
+
+
+def _publish_bootstrap_package(inst: Instance, features: list[str] | None) -> str:
+    """Import + publish AcuBootstrap into inst.tenant (data plane only)."""
     with (
         output.step(f"publishing {bootstrap.PACKAGE_NAME} to {inst.tenant}"),
         AcumaticaClient(inst) as client,
     ):
-        result = bootstrap.publish(client, features=features)
-    output.success(f"{bootstrap.PACKAGE_NAME} {result}")
-    # unconditional: the publish restarts the site BEFORE its DB transaction
-    # commits, so the restarted domain caches the feature slot pre-plugin
-    # (verified live: gated screens stay 403 until one more recycle); on the
-    # skip path a recycle is the cheap way to make a resumed run sound too
+        return bootstrap.publish(client, features=features)
+
+
+def _recycle_after_bootstrap(inst: Instance, mgr: TenantManager | None) -> None:
+    """Post-publish app-pool recycle when the control plane is available.
+
+    The publish restarts the site BEFORE its DB transaction commits, so the
+    restarted domain caches the feature slot pre-plugin (verified live:
+    gated screens stay 403 until one more recycle). On the skip path a
+    recycle is the cheap way to make a resumed run sound too. Hosted
+    (no ACU_SSH): warn and continue — the customer must restart the site
+    another way before feature-gated apply can succeed.
+    """
+    if mgr is None and not inst.ssh:
+        output.warn(
+            "ACU_SSH not set: skipped app-pool recycle; "
+            "feature-gated screens may stay 403 until the site restarts"
+        )
+        return
+    if mgr is None:
+        mgr = TenantManager(inst)
     with output.step("recycling app pool (feature set loads at app start)"):
         mgr.recycle_app_pool()
     with output.step("waiting for the site to come back"):
-        firstlogin.initialize_admin_password(inst, tenant=login_name)
+        firstlogin.initialize_admin_password(inst, tenant=inst.tenant)
+
+
+def _bootstrap_tenant(inst: Instance, mgr: TenantManager, login_name: str) -> None:
+    """Publish the bootstrap package into the fresh tenant (data plane).
+
+    Idempotent on content, not existence (V4): publish() skips only when the
+    published package carries the digest of the package built now. The
+    session targets the new tenant explicitly (V5), never a config default.
+    Tenant create always has SSH (TenantManager already constructed), so
+    the post-publish recycle always runs on this path.
+    """
+    inst = inst.model_copy(update={"tenant": login_name})
+    features = _bootstrap_features()
+    result = _publish_bootstrap_package(inst, features)
+    output.success(f"{bootstrap.PACKAGE_NAME} {result}")
+    _recycle_after_bootstrap(inst, mgr)
+
+
+@cli.command("bootstrap")
+@click.option(
+    "--export",
+    "export_path",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=None,
+    help="Write the package zip to PATH (offline; no REST, no SSH) "
+    "for Customization Projects UI import",
+)
+@click.pass_context
+def bootstrap_cmd(ctx: click.Context, export_path: Path | None) -> None:
+    """Publish AcuBootstrap into the session tenant (or export the package zip).
+
+    Hosted / no-SSH path: CustomizationApi publish is pure REST, so this
+    command never requires ACU_SSH. When SSH is set, an app-pool recycle
+    follows publish so feature-gated screens load; when unset, a warning
+    notes that the site may need another restart before apply.
+
+    --export writes the same feature-spliced package that publish would
+    import, with no HTTP and no password — the SM204505 UI-import fallback.
+    """
+    features = _bootstrap_features()
+    if export_path is not None:
+        if not export_path.parent.exists():
+            raise SystemExit(f"{export_path.parent}: directory does not exist")
+        export_path.write_bytes(bootstrap.package_zip(features))
+        output.success(f"wrote {export_path}")
+        return
+    inst = _resolve_instance(ctx)
+    if not inst.tenant:
+        raise SystemExit(
+            "tenant not set (pass --tenant, "
+            "or put ACU_TENANT in .env or the environment)"
+        )
+    result = _publish_bootstrap_package(inst, features)
+    output.success(f"{bootstrap.PACKAGE_NAME} {result}")
+    _recycle_after_bootstrap(inst, mgr=None)
 
 
 @tenant_group.command("delete")
@@ -558,7 +628,18 @@ def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
     with AcumaticaClient(inst) as client:
         for path in paths:
             baseline = seed.load_baseline(path)
-            drifts += seed.diff(client, baseline)
+            # same file banner as apply so a long multi-file diff shows
+            # progress instead of silence until the final status line
+            output.data(
+                f"{path} -> {inst.tenant} on {inst.base_url} ({baseline.entity})"
+            )
+            file_drifts = seed.diff(client, baseline)
+            drifts += file_drifts
+            n = 1 if isinstance(baseline, seed.ActionFile) else len(baseline.records)
+            if file_drifts:
+                output.data(f"  {n} record(s), {len(file_drifts)} drift(s)")
+            else:
+                output.data(f"  {n} record(s) ok")
     _exit_on_drift(inst, drifts, len(paths))