@collective-intelligence/cli 0.3.3 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +86 -5
  2. package/dist/cli.js +51 -43
  3. package/package.json +5 -5
package/README.md CHANGED
@@ -432,7 +432,9 @@ ends with one `{"kind":"result",...}` line, or with one
432
432
  `archiveId` and `status`. `nextAction` is the command you ran, with all its
433
433
  options and with quoting for the shell, plus what it needs to continue: the
434
434
  `--archive-id` of an upload that began, or the run to read. A run that does not
435
- complete is an error; `nextAction` names `--resume` for a stopped run.
435
+ complete is an error; `nextAction` names `--resume` for a stopped run. The
436
+ error line also carries the Failure Signal fields of
437
+ [Errors and diagnostics](#errors-and-diagnostics).
436
438
  Persisted and wire values use lower snake_case; flag names use kebab-case.
437
439
 
438
440
  **Ctrl-C.** The first Ctrl-C stops the upload, the download or the follow at
@@ -558,7 +560,8 @@ JSON mode emits newline-delimited records with `kind: progress`, `result`, or
558
560
  `error`. An accepted operation is progress, not success. The command follows
559
561
  resumable durable operation streams and exits successfully only after every
560
562
  required operation succeeds. Failed, blocked or awaiting-continuation outcomes
561
- exit nonzero with the operation ID and Backend-authored guidance. The default
563
+ exit nonzero with the operation ID and the Failure Signal of
564
+ [Errors and diagnostics](#errors-and-diagnostics). The default
562
565
  overall deadline is 300,000 ms; `--timeout-ms <positive-integer>` changes it.
563
566
  Timeout errors preserve the operation ID and last observed event sequence;
564
567
  rerun the same intent or use `ci package operation reconnect` to follow it.
@@ -1070,14 +1073,14 @@ ci package promote --backend-url https://ci.example.com \
1070
1073
  --release release_123 --idempotency-key build-482-promote
1071
1074
 
1072
1075
  ci package releases --backend-url https://ci.example.com \
1073
- --organization org_123 --package acme.analytics
1076
+ --organization <organization-id> --package acme.analytics
1074
1077
 
1075
1078
  ci package install --backend-url https://ci.example.com \
1076
- --organization org_123 --package acme.analytics \
1079
+ --organization <organization-id> --package acme.analytics \
1077
1080
  --release release_123 --idempotency-key org-123-install-release-123
1078
1081
 
1079
1082
  ci package update --backend-url https://ci.example.com \
1080
- --organization org_123 --installation installation_123 \
1083
+ --organization <organization-id> --installation installation_123 \
1081
1084
  --release release_456 --idempotency-key org-123-update-release-456
1082
1085
  ```
1083
1086
 
@@ -1121,3 +1124,81 @@ application in the Dashboard External Apps page. The response shows
1121
1124
  `clientSecret` once; store it server-side immediately, because CI keeps only its
1122
1125
  hash. Each rotation invalidates the previous secret. See
1123
1126
  [Provision a secret for a package-created application](../../../docs/reference/package-release-cli.md#provision-a-secret-for-a-package-created-application).
1127
+
1128
+ ## Errors and diagnostics
1129
+
1130
+ Every `ci` command ends a failure with one Failure Signal: the Summary (what
1131
+ failed), the Cause (the error tag, its reason and identifiers), the Remedy (the
1132
+ steps that remove the Cause), the Retry Class and the Reference. The words
1133
+ follow the CLI Error Signal glossary of the project wiki. A Failure Signal
1134
+ holds only product-authored text and identifiers, never a Raw Message.
1135
+
1136
+ In text mode the failure is one labelled block on stderr:
1137
+
1138
+ ```text
1139
+ Error: Skills still use the tool that this change removes.
1140
+ Cause: AiToolInstanceRepositoryError (referenced_by_skills); skillIds: skill-1, skill-2; toolFqn: com.acme.tools.search; toolInstanceId: tool-1
1141
+ Fix: 1. Remove the tool from these skills, or keep it declared in the package.
1142
+ 2. Start a new operation after the fix.
1143
+ ci deploy --organization 0190a2b4-7c3e-7d1a-9f00-4b2c8e6d1a01 --declaration ./crm.ts
1144
+ Retry: terminal (the same command fails again until the Cause is fixed)
1145
+ Reference: Operation ID operation-1; Diagnostic ID diag-1
1146
+ ```
1147
+
1148
+ - **Retry Class.** `retryable` means that a later attempt can pass. `terminal`
1149
+ means that the same command fails again until the Cause is fixed; a terminal
1150
+ Signal never advises a retry of the same operation.
1151
+ - **Remedy commands.** A Remedy step can carry a Remedy Action. The CLI prints
1152
+ the exact command line for it under the step: `new_operation` repeats your
1153
+ invocation with `--idempotency-key <new-key>` (and `--declaration <module>`
1154
+ in place of `--resume`), `continue_operation` prints
1155
+ `ci package operation continue`, `login` prints `ci login <API URL>`, and
1156
+ `diagnostics` prints `ci diagnostics show <diagnostic-id>`. A `401` reply
1157
+ adds a `ci login` step.
1158
+ - **JSON record.** With `--json`, and always for `ci transfer`, the failure is
1159
+ one record on stdout with `kind: "error"`, `summary`, `cause`, `remedy`
1160
+ (each step with its `command`), `retryClass`, `reference`, `nextAction` (the
1161
+ last Remedy command) and `diagnosticDetail`. The older fields of the
1162
+ `ci deploy`, `ci transfer` and `ci orgs` records stay.
1163
+ - **Exit codes.** A failed command exits `1` and an interrupted command exits
1164
+ `130`, for retryable and terminal failures alike.
1165
+ - **Older Backend.** A Backend that sends no Failure Signal gets a block built
1166
+ from the error, the HTTP status and the reply message.
1167
+ - **Malformed IDs.** `--organization`, `--operation`, `--diagnostic` and the
1168
+ `ci diagnostics show` ID are UUIDs. The CLI refuses another value before any
1169
+ request, for example
1170
+ `--operation must be an Operation ID (a UUID); got 'not-a-uuid'.`, with the
1171
+ Cause `InvalidIdOptionError` and a Remedy that names where to find the ID.
1172
+ - **Invalid request.** A `400` reply that names no reason prints
1173
+ `The backend rejected the request as invalid (HTTP 400): <METHOD> <path>.`
1174
+ and a Remedy step to check the values in the request.
1175
+
1176
+ ### Diagnostic Detail
1177
+
1178
+ The Diagnostic Detail is the full failure behind a Diagnostic ID: the Raw
1179
+ Messages, the error chain, the stack and the log annotations. The Backend keeps
1180
+ it for 30 days by default. After a failure with a Diagnostic ID, the CLI reads
1181
+ the Diagnostic Detail with your own credential and prints it in a section under
1182
+ the block (or in `diagnosticDetail` with `--json`). When you cannot read it,
1183
+ the section names who can and the command to run. Read it again later:
1184
+
1185
+ ```sh
1186
+ ci diagnostics show <diagnostic-id> [--organization <organization-id>] [--json]
1187
+ ```
1188
+
1189
+ The command also accepts `--backend-url` and `--profile`. Without
1190
+ `--organization` it uses the Current Organization of your profile. With
1191
+ `--json` it prints the record.
1192
+
1193
+ The origin of the failure decides who can read its Diagnostic Detail:
1194
+
1195
+ | Failure origin | Readers |
1196
+ | --------------------------------- | ------------------------------------------------------------------ |
1197
+ | Package Operation | `extensions:manage` in the Organization, or `tenant:manage` |
1198
+ | HTTP request in an Organization | `organization:self_manage` in the Organization, or `tenant:manage` |
1199
+ | Tenant route or no signed-in user | `tenant:manage` |
1200
+
1201
+ Every caller sees the Failure Signal. Being the user whose request failed does
1202
+ not grant the Diagnostic Detail. A Host failure keeps its own Diagnostic ID and
1203
+ `ci package diagnostics trace`. See
1204
+ [Failure output and Diagnostic Detail](../../../docs/reference/package-release-cli.md#failure-output-and-diagnostic-detail).