@soat/cli 0.19.2 → 0.20.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import { load } from "js-yaml";
 import * as os from "node:os";
 
 //#region package.json
-var version = "0.19.2";
+var version = "0.20.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -3970,7 +3970,7 @@ var routes = {
   "create-guardrail": {
     serviceClass: "Guardrails",
     operationId: "createGuardrail",
-    description: "Creates a new guardrail in the project. The `document` is validated on write: `class` must be a literal (A/B/C/D) or a JSON Logic expression, and every variable it (and `guard`) reference must resolve to the `args.*` / `context.*` / `soat.*` namespaces — an out-of-catalog `soat.*` key is rejected with 400.",
+    description: "Creates a new guardrail in the project, archiving its document as version 1. The `document` is validated on write: `class` must be a literal (A/B/C/D) or a JSON Logic expression, and every variable it (and `guard`) reference must resolve to the `args.*` / `context.*` / `soat.*` namespaces — an out-of-catalog `soat.*` key is rejected with 400.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
     httpMethod: "post",
     pathParams: [],
@@ -4011,6 +4011,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "version_label",
+      "description": "Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "get-guardrail": {
@@ -4032,7 +4038,7 @@ var routes = {
   "update-guardrail": {
     serviceClass: "Guardrails",
     operationId: "updateGuardrail",
-    description: "Updates an existing guardrail. A `document` write increments `version` and archives the prior document as a GuardrailVersion; metadata-only edits (name / description / context) leave the version untouched.",
+    description: "Updates an existing guardrail. A `document` write that actually changes the policy increments `version` and archives the new document as a GuardrailVersion; metadata-only edits (name / description / context), and re-writing the document the guardrail already holds, leave the version untouched.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
     httpMethod: "patch",
     pathParams: ["guardrail_id"],
@@ -4073,6 +4079,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "version_label",
+      "description": "Optional tag for the config version this write archives (e.g. `pre-tightening`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes no policy, since no version is created.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "delete-guardrail": {
@@ -4091,10 +4103,38 @@ var routes = {
       "in": "path"
     }]
   },
+  "list-guardrail-versions": {
+    serviceClass: "Guardrails",
+    operationId: "listGuardrailVersions",
+    description: "Returns the guardrail's archived configurations, newest first. A version is written on create and on every subsequent write that changes the policy `document` — through the REST API or a formation apply alike. Metadata-only edits (name, description, context binding) do not archive a version. See [Versioning](/docs/modules/guardrails#versioning).",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
+    httpMethod: "get",
+    pathParams: ["guardrail_id"],
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "guardrail_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
   "get-guardrail-version": {
     serviceClass: "Guardrails",
     operationId: "getGuardrailVersion",
-    description: "Returns the exact `document` that governed at a given version. Approval items, activity entries, and exceptions record the version that governed them, so the audit chain survives edits.",
+    description: "Returns the exact configuration — and so the exact `document` — that governed at a given version. Approval items, activity entries, and exceptions record the version that governed them, so the audit chain survives edits.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
     httpMethod: "get",
     pathParams: ["guardrail_id", "version"],
@@ -4113,6 +4153,34 @@ var routes = {
       "in": "path"
     }]
   },
+  "restore-guardrail-version": {
+    serviceClass: "Guardrails",
+    operationId: "restoreGuardrailVersion",
+    description: "Writes an archived version's `document` back as the guardrail's live policy, which archives it again as a **new** version rather than rewinding the counter — so an approval item or exception citing any version in between still resolves. The restore runs through the ordinary update path, so the archived document is re-validated; restoring the policy the guardrail already holds is a no-op and archives nothing.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
+    httpMethod: "post",
+    pathParams: ["guardrail_id", "version"],
+    queryParams: [],
+    flags: [{
+      "name": "guardrail_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "version",
+      "description": "",
+      "required": true,
+      "type": "integer",
+      "in": "path"
+    }, {
+      "name": "label",
+      "description": "Optional tag for the version the restore creates. Defaults to `restored from v<version>`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
+  },
   "evaluate-guardrail": {
     serviceClass: "Guardrails",
     operationId: "evaluateGuardrail",
@@ -4939,6 +5007,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "version_label",
+      "description": "Optional tag for the version this create archives, e.g. `initial`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "validate-orchestration": {
@@ -5045,6 +5119,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "version_label",
+      "description": "Optional tag for the version this write archives, e.g. `pre-rewire`. Ignored when the write changes no graph field, since no version is archived.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "delete-orchestration": {
@@ -5063,6 +5143,84 @@ var routes = {
       "in": "path"
     }]
   },
+  "list-orchestration-versions": {
+    serviceClass: "Orchestrations",
+    operationId: "listOrchestrationVersions",
+    description: "Returns the orchestration's archived graphs, newest first. A version is written on create and on every subsequent write that changes the graph (`nodes`, `edges`, `state_schema`, `input_schema`) — through the REST API or a formation apply alike. Metadata-only edits (name, description) do not archive a version. See [Versioning](/docs/modules/orchestrations#versioning).",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/orchestrations",
+    httpMethod: "get",
+    pathParams: ["orchestration_id"],
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "orchestration_id",
+      "description": "Public ID of the orchestration (orch_...)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
+  "get-orchestration-version": {
+    serviceClass: "Orchestrations",
+    operationId: "getOrchestrationVersion",
+    description: "Returns the exact graph a given version describes. Every run records the version it started on in `orchestration_version` and executes that graph for its whole life, so this is how you read the topology a run actually took — including a run whose orchestration has been rewired since.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/orchestrations",
+    httpMethod: "get",
+    pathParams: ["orchestration_id", "version"],
+    queryParams: [],
+    flags: [{
+      "name": "orchestration_id",
+      "description": "Public ID of the orchestration (orch_...)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "version",
+      "description": "The archived version number",
+      "required": true,
+      "type": "integer",
+      "in": "path"
+    }]
+  },
+  "restore-orchestration-version": {
+    serviceClass: "Orchestrations",
+    operationId: "restoreOrchestrationVersion",
+    description: "Writes an archived version's graph back as the orchestration's live definition, which archives it again as a **new** version rather than rewinding the counter — so a run pinned to any version in between still resolves the graph it started on. The restore runs through the ordinary update path, so the archived graph goes through the same static validation as an authored one. Node resource references (`agent_id`, `tool_id`, `orchestration_id`) resolve when a run reaches the node, so a target deleted since the snapshot was taken restores cleanly and surfaces as a failed run rather than a `400`. Restoring the graph the orchestration already holds is a no-op and archives nothing. Runs already in flight are unaffected either way — a restore is an ordinary edit, and pinning is what keeps it from reaching them.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/orchestrations",
+    httpMethod: "post",
+    pathParams: ["orchestration_id", "version"],
+    queryParams: [],
+    flags: [{
+      "name": "orchestration_id",
+      "description": "Public ID of the orchestration (orch_...)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "version",
+      "description": "The archived version number",
+      "required": true,
+      "type": "integer",
+      "in": "path"
+    }, {
+      "name": "label",
+      "description": "Optional tag for the version the restore creates. Defaults to `restored from v<version>`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
+  },
   "list-orchestration-runs": {
     serviceClass: "Orchestrations",
     operationId: "listOrchestrationRuns",
@@ -7635,6 +7793,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "version_label",
+      "description": "Optional tag for the version this create archives, e.g. `initial`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "get-workflow": {
@@ -7697,6 +7861,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "version_label",
+      "description": "Optional tag for the version this write archives, e.g. `pre-rewire`. Ignored when the write changes no definition field, since no version is archived.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "delete-workflow": {
@@ -7714,6 +7884,84 @@ var routes = {
       "type": "string",
       "in": "path"
     }]
+  },
+  "list-workflow-versions": {
+    serviceClass: "Workflows",
+    operationId: "listWorkflowVersions",
+    description: "Returns the workflow's archived state machines, newest first. A version is written on create and on every subsequent write that changes the definition (`states`, `transitions`, `payload_schema`) — through the REST API or a formation apply alike. Metadata-only edits (name, description) do not archive a version. See [Versioning](/docs/modules/workflows#versioning).",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/workflows",
+    httpMethod: "get",
+    pathParams: ["workflow_id"],
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "workflow_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
+  "get-workflow-version": {
+    serviceClass: "Workflows",
+    operationId: "getWorkflowVersion",
+    description: "Returns the exact state machine a given version describes. Every task records the version it entered on in `workflow_version` and runs on that machine for its whole life, so this is how you read the definition a task is actually being validated against — including a task whose workflow has been rewired since.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/workflows",
+    httpMethod: "get",
+    pathParams: ["workflow_id", "version"],
+    queryParams: [],
+    flags: [{
+      "name": "workflow_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "version",
+      "description": "The archived version number",
+      "required": true,
+      "type": "integer",
+      "in": "path"
+    }]
+  },
+  "restore-workflow-version": {
+    serviceClass: "Workflows",
+    operationId: "restoreWorkflowVersion",
+    description: "Writes an archived version's state machine back as the workflow's live definition, which archives it again as a **new** version rather than rewinding the counter — so a task pinned to any version in between still runs on the machine it entered on. The restore runs through the ordinary update path, so the archived definition goes through the same validation as an authored one. That includes resolving every `on_enter` dispatch target, so restoring a version whose agent or orchestration has since been deleted fails with `400` rather than writing a definition that would strand a task on entry. Restoring the definition the workflow already holds is a no-op and archives nothing. Tasks already in flight are unaffected either way — a restore is an ordinary edit, and pinning is what keeps it from reaching them.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/workflows",
+    httpMethod: "post",
+    pathParams: ["workflow_id", "version"],
+    queryParams: [],
+    flags: [{
+      "name": "workflow_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "version",
+      "description": "The archived version number",
+      "required": true,
+      "type": "integer",
+      "in": "path"
+    }, {
+      "name": "label",
+      "description": "Optional tag for the new version the restore archives. Defaults to `restored from vN`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "type": "module",
   "dependencies": {
     "@inquirer/input": "^5.1.2",
@@ -8,7 +8,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.19.2"
+    "@soat/sdk": "0.20.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",