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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.8.2
+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)
 

{acumatica_cli-0.8.2 → 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)
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.8.2"
+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.2 → 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")