mammoth-cli 2.0.44__tar.gz → 2.0.46__tar.gz

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.44
+Version: 2.0.46
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.8,>=0.7.18
+Requires-Dist: mammoth-io<0.8,>=0.7.19
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.0.44"
+__version__ = "2.0.46"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.44
+version: 2.0.46
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines (join, merge, pivot, filter, clean), dashboards, exports, and handoffs."
 ---
 
@@ -82,6 +82,7 @@ mammoth view transform --help              # every data transformation
 | Rank, running total, previous row | `view transform window` |
 | A dashboard | `dashboard create-blank` ([dashboards](references/recipes/dashboards.md)) |
 | Deliver the rows | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
+| Run something on a schedule or on new data (refresh, append, alert) | `automation create`: a condition (`at_specific_time`, new file in a folder, ...) and tasks (`run_data_retrieval`, `append_data`, `send_an_alert`, `pull_cloud_files`). `schedule create` only pulls a connector's data. A dataset made from an uploaded file has no source to refresh from; say so. Full recipe, including a known `automation get` backend caveat: [recurring work](references/recipes/scheduling.md) |
 
 A search with no full match returns `suggestions` and a `hint`. Before you
 conclude the CLI cannot do something the web app does, check

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/automation.md

@@ -70,4 +70,4 @@ Example: `mammoth automation update 123 --input '{"patch": [{"op": "replace", "p
 
 Result: `AutomationUpdateResult`; mutation `external_effect`, confirmation `yes_always`, wait policy `not_async`.
 
-Status on release: observed blocker — cli_error: CLI rejected 'name' field; error message says accepted field is 'patch' (nested patch object), not documented in agent_example. Re-check before relying on it.
+Status on release: CLI defect fixed, untried since — CLI defect fixed in mammoth-io 0.7.19 / mammoth-cli 2.0.46: AutomationsAPI.update sent path=status value='resume' to the backend verbatim; the backend's wire vocabulary for that path is 'suspend'/'restore' (apiv2/apiv2/automations/schema.py AutomationStatusVa…

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/index.md

@@ -17,5 +17,6 @@ hashes; stop on ambiguous schemas, authorization errors, or unknown effects.
 - [typed ETL discovery](typed-etl-discovery.md)
 - [exports and artifacts](exports.md)
 - [dashboards](dashboards.md)
+- [recurring work: automations and schedules](scheduling.md)
 - [trash, recovery and cleanup](cleanup.md)
 - [deliverable retention and cleanup authorization](../retention.md)

mammoth_cli-2.0.46/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -0,0 +1,122 @@
+# Recurring work: automations and schedules
+
+Two different resources both look like "make this run on its own." Pick by
+what the task actually needs to run, not by the word "schedule" in the
+request:
+
+- **`automation`** — the general-purpose recurring/triggered task engine.
+  Use it for `run_data_retrieval` (refresh a cloud dataset), `append_data`
+  (add new rows from a folder or dataset), `send_an_alert` (email), and
+  `pull_cloud_files` (land new cloud files into a folder). Recurrence is one
+  of the automation's `conditions`, type `at_specific_time`, alongside the
+  `tasks` it runs. This is what "schedule a daily refresh" almost always
+  means.
+- **`schedule`** — a single, narrower resource that only pulls a cloud
+  connector's data (`pull_cloud_data` work item). It has no other work item
+  type on this backend (`ALLOWED_TASK_RESOURCE_MAP` in mvc-service only maps
+  `pull_cloud_data`); do not try to fit `append_data`/`send_an_alert`/
+  `pull_cloud_files` into a `schedule create` body, it will be rejected.
+  `schedule list` is unimplemented on every backend release tested so far
+  (`GET .../schedules` always returns HTTP 400 `5GENR011 NOT_IMPLEMENTED`,
+  not intermittently) — do not poll it; there is currently no way to list
+  schedules for a project from the CLI. Use `schedule get SCHEDULE_ID` with
+  an id you already have (for example from a dataset's own automation/task
+  metadata) instead.
+
+`schema find "recurring work"` phrasing (e.g. "schedule a daily refresh",
+"run every week automatically") resolves to `automation create`.
+
+## Create a recurring automation
+
+```bash
+mammoth schema get automation.create   # confirm the current task/condition shapes first
+mammoth automation create 'Nightly refresh' --yes --input '{
+  "description": "Refresh dataset 42 every day at 02:00 UTC",
+  "tasks": [
+    {"task_type": "run_data_retrieval", "details": {"ds_details": [{"ds_id": 42}]}}
+  ],
+  "conditions": [
+    {"condition_type": "at_specific_time", "details": {
+      "frequency": "daily", "interval": 1, "start_at": "2026-01-01T02:00:00Z"
+    }}
+  ]
+}'
+```
+
+The other three task types take the shapes documented in `schema get
+automation.create` under `tasks[].details`:
+
+- `append_data`: `destination_dataset_ids` (required) plus either
+  `source_folder_resource_id` or `source_dataset_id`.
+- `send_an_alert`: `alert_type` ("email"), `recipients`, `subject`.
+- `pull_cloud_files`: `connector_key`, `connection_key`,
+  `cloud_source_folder_path`, `destination_folder_resource_id`.
+
+`conditions`/`condition_mode` are optional; an automation with no
+`at_specific_time` condition runs only on demand (`automation update ID
+--yes --input '{"patch": [{"op": "command", "path": "run", "value": {}}]}'`)
+or via its other condition types (new file in a folder, etc.), not on a
+recurrence.
+
+## Read it back
+
+```bash
+mammoth automation get AUTOMATION_ID
+mammoth automation list
+```
+
+**Known backend defect (observed on release, not a CLI bug):**
+`automation get AUTOMATION_ID` on an automation `automation create` just
+returned can come back HTTP 500 with an empty body — deterministically, not
+an eventual-consistency race (confirmed by three retries seconds apart in
+`docs/capability-evidence/fixture-sweep-20260919/`). `automation list` can
+also fail to show that same automation. Both were root-caused by reading
+mvc-service (not by a live re-run — see `docs/release-capability-matrix.json`
+`REL-181`): the leading candidate is an unconditional `automation_tasks[0]`
+index in `apiv2/apiv2/automations/utils.py` `get_automation_tasks()`, which
+raises an unhandled `IndexError` when a GET's task lookup comes back empty —
+matching the empty response body (a normal validation error returns a JSON
+envelope; this does not). Do not report "the automation vanished"; if `get`
+or `list` fail this way right after a create, treat the create's own 200/202
+response and `automation_id` as the source of truth, and say so in the
+report. This is not something the CLI can work around — do not retry
+`automation get` more than once for this.
+
+## Update: disable / enable, change tasks, run now
+
+```bash
+# Suspend (disable)
+mammoth automation update AUTOMATION_ID --yes --input '{"patch": [{"op": "replace", "path": "status", "value": "suspend"}]}'
+# Resume (enable) -- the SDK sends this as the backend's real wire value ("restore"); pass "resume" here regardless
+mammoth automation update AUTOMATION_ID --yes --input '{"patch": [{"op": "replace", "path": "status", "value": "resume"}]}'
+# Change fields (name/description/tasks/conditions) -- at least one required
+mammoth automation update AUTOMATION_ID --yes --input '{"patch": [{"op": "replace", "path": "details", "value": {"description": "new description"}}]}'
+# Run immediately, independent of any recurrence condition
+mammoth automation update AUTOMATION_ID --yes --input '{"patch": [{"op": "command", "path": "run", "value": {}}]}'
+```
+
+`patch` is the only top-level input field; a bare `name`/`description` field
+is rejected (`missing_field`, `patch` is required) — this is documented
+behavior, not a bug.
+
+## Delete
+
+```bash
+mammoth automation delete AUTOMATION_ID --yes    # permanent
+mammoth automation trash AUTOMATION_ID           # reversible; automation.restore undoes it
+```
+
+## Schedule (pull_cloud_data only)
+
+```bash
+mammoth schema get schedule.create
+mammoth schedule create --yes --input '{"spec": {
+  "rrule": {"frequency": "daily", "start": "2026-01-01T02:00:00Z"},
+  "work_items": [{"name": "pull_cloud_data", "execution_params": {
+    "schedule_type": "moment", "first_pull_at": "now", "on_refresh_action": "replace"
+  }, "args": [DATASET_ID]}]
+}}'
+mammoth schedule get SCHEDULE_ID
+mammoth schedule update SCHEDULE_ID --yes --input '{"patch": [{"op": "replace", "path": "status", "value": "pause"}]}'
+mammoth schedule delete SCHEDULE_ID --yes
+```

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/mammoth_cli/commands/schema.py

@@ -70,6 +70,10 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.export.dataset": (
         "send copy branch out rows into a dataset in another project append union stack rows"
     ),
+    "automation.create": (
+        "schedule scheduled recurring repeat refresh rerun run every day daily week weekly "
+        "hour hourly month monthly automatically trigger alert email a dataset pipeline"
+    ),
     # One entry per ``view transform`` command, in the words a user states a
     # goal in rather than Mammoth's own task names.  This is the CLI's version
     # of the web app's Transform menu; keep every transform listed.

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.44"
+version = "2.0.46"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.7.18,<0.8)",
+    "mammoth-io (>=0.7.19,<0.8)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/spec/manifests/commands/automation.yaml

@@ -120,7 +120,12 @@ commands:
   - CT-AUTOMATION-GET-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'B04 SERVER_VARIANCE: observed on release returning HTTP 500 with an
+    empty body for an automation automation.create just returned (deterministic, not eventual
+    consistency; see docs/capability-evidence/fixture-sweep-20260919/). Backend defect, not a CLI
+    request-shape issue; root-caused (not live-reproduced) to mvc-service apiv2/apiv2/automations/utils.py
+    get_automation_tasks() indexing automation_tasks[0] unconditionally -- see REL-181 in
+    docs/release-capability-matrix.json for the full trace. Do not retry more than once.'
   reviewed_by: primary
 - command_id: automation.list
   command_path: automation list

{mammoth_cli-2.0.44 → mammoth_cli-2.0.46}/spec/manifests/commands/schedule.yaml

@@ -147,7 +147,13 @@ commands:
   - CT-SCHEDULE-LIST-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'B04 SERVER_VARIANCE: schedule list may return 405.'
+  known_restrictions: 'B04 SERVER_VARIANCE: unconditionally unimplemented on every backend
+    release tested, not intermittent -- GET .../schedules always returns HTTP 400 with error
+    code 5GENR011 NOT_IMPLEMENTED (mvc-service apiv2/apiv2/schedules/controller.py
+    ScheduleController.list_schedules always raises ClientError(not_implemented_error); its
+    own docstring says schedules carry no workspace/project reference to list by). Do not poll
+    it; there is no way to list schedules for a project from the CLI today. Use `schedule get
+    SCHEDULE_ID` with an id obtained elsewhere.'
   reviewed_by: primary
 - command_id: schedule.update
   command_path: schedule update